LinkedIn Gateway API

🎯 Overview

LinkedIn Gateway bridges the gap between LinkedIn's web interface and your applications by providing:

Chrome Extension: Captures LinkedIn session and proxies requests
REST API: Clean, documented endpoints for LinkedIn data
Self-Hosted: Full control over your data and infrastructure
Open Core: Free and open source for self-hosting

Dual Execution Architecture

The system supports two modes of operation:

Browser Proxy Mode (Default): Routes requests through the Chrome extension using your active LinkedIn session
Server-Side Execution: Direct API calls from the backend using stored session cookies (requires self-hosted deployment)

✅ Key Features

Complete LinkedIn API Coverage

• Feed operations (fetch posts with engagement data)
• Connection management (send/accept requests)
• Messaging (send direct messages)
• Profile scraping (extract profile data)
• Comment operations (post & reply)
• Reactions scraping (fetch post likes with user details)
• User comments history (fetch all comments made by a profile)

Dual Execution Modes

• Server-side execution for automated workflows
• Browser proxy mode for enhanced session reliability
• Seamless switching between modes
• Automatic fallback handling

Enterprise-Ready

• API key authentication with rate limiting
• PostgreSQL database for data persistence
• WebSocket support for real-time operations
• Comprehensive error handling and logging

Production Deployment

• Docker Compose setup included
• Automated database migrations
• Health checks and monitoring
• HTTPS support with OAuth integration

🏗️ Architecture

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐
│   Your App      │         │  LinkedIn        │         │   Chrome        │
│   (API Client)  │────────▶│  Gateway API     │◀────────│   Extension     │
│                 │  REST   │  (FastAPI)       │  WSS    │   (Proxy)       │
└─────────────────┘         └──────────────────┘         └─────────────────┘
                                     │                            │
                                     │                            │
                                     ▼                            ▼
                            ┌──────────────────┐        ┌─────────────────┐
                            │   PostgreSQL     │        │   LinkedIn      │
                            │   Database       │        │   Internal API  │
                            └──────────────────┘        └─────────────────┘

Execution Modes

1. Server-Side Execution (`server_call=true`)

The backend directly calls LinkedIn's internal APIs using stored session cookies.

✅ Pros:

• Fully automated, no browser required
• Faster response times
• Suitable for batch operations

⚠️ Cons:

• Requires valid LinkedIn session cookies
• May need periodic session refresh

2. Browser Proxy Mode (`server_call=false`)

Requests are proxied through the Chrome extension, which uses the user's active LinkedIn session.

✅ Pros:

• Always uses fresh, valid session
• More reliable for long-running operations
• Automatic session management

⚠️ Cons:

• Requires Chrome extension to be running
• Slightly higher latency

🚀 Quick Start

Prerequisites

Docker & Docker Compose (required - must be installed before running the installer)
OR Python 3.11+ and PostgreSQL (for manual setup without Docker)
Google Chrome or Chromium-based browser
LinkedIn Account (required for functionality)

Option 1: Docker Deployment (Recommended)

# Clone the repository
git clone https://github.com/vcentea/linkedin-gateway.git
cd linkedin-gateway

# Run the installation script
# Windows
deployment\scripts\install-core.bat

# Linux/Mac
chmod +x deployment/scripts/install-core.sh
./deployment/scripts/install-core.sh

# Access the API
# API: http://localhost:7778
# API Docs: http://localhost:7778/docs
# Health Check: http://localhost:7778/health

📚 Installing Docker

• Linux: Ubuntu/Debian or CentOS/RHEL
• Windows/macOS: Docker Desktop

Option 2: Local Development

# 1. Set up virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate  # Windows

# 2. Install dependencies
cd backend
pip install -r requirements/base.txt

# 3. Configure environment
cp .env.example .env
# Edit .env with your database credentials

# 4. Run database migrations
alembic upgrade head

# 5. Start the server
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Chrome Extension Setup

cd chrome-extension

# Install dependencies
npm install

# Build for development
npm run build:dev

# Build for production
npm run build:prod

Load in Chrome:

Go to chrome://extensions/
Enable "Developer mode"
Click "Load unpacked"
Select chrome-extension/dist-dev/ (or dist-prod/)

🔐 Authentication

LinkedIn Gateway uses API keys for authentication. Generate your API key through the web interface or OAuth flow.

API Key Authentication

All API endpoints require authentication using an API key. You can provide the key in two ways:

1. Header Authentication (Recommended)

Pass the API key in the X-API-Key header:

curl -X POST https://localhost:7778/api/v1/feed/posts \
  -H "X-API-Key: LKG_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"start_index": 0, "count": 10, "server_call": false}'

2. Body Authentication

Include the API key in the request body:

{
  "api_key": "LKG_your_api_key_here",
  "start_index": 0,
  "count": 10,
  "server_call": false
}

💡 server_call Parameter

All endpoints support dual execution modes via the server_call parameter:

• server_call: false (default) - Executes via browser extension proxy (requires extension installed and connected)
• server_call: true - Executes directly from server using stored LinkedIn session (requires self-hosted deployment with valid session)

OAuth 2.0 Flow

LinkedIn Gateway supports LinkedIn OAuth for user authentication:

User initiates login via Chrome extension
Extension redirects to LinkedIn OAuth
LinkedIn redirects back with authorization code
Backend exchanges code for access token
User session is created with JWT token
API key is generated for programmatic access

🔑 API Key Management

• Format: LKG_prefix_secret
• Storage: Hashed in PostgreSQL database
• Scope: Per-user, with rate limiting
• Rotation: Users can regenerate keys anytime

📚 API Reference

All endpoints support dual execution modes via the server_call parameter.

Base URL: http://localhost:7778 (or your deployed server URL)

Feed Operations

POST `/api/v1/feed/posts`

Fetch posts from your LinkedIn feed with full engagement data.

Headers:

X-API-Key: LKG_your_api_key_here
Content-Type: application/json

Request Body:

{
  "start_index": 0,
  "count": 10,
  "server_call": false
}

Parameters:

Parameter	Type	Description
`start_index`	integer	Starting index for posts (default: 0)
`count`	integer	Number of posts to fetch (1-50, default: 10)
`server_call`	boolean	Execution mode (false: proxy, true: server)

Response:

[
  {
    "id": 1,
    "postid": "urn:li:activity:7123456789",
    "ugcpostid": "urn:li:ugcPost:7123456789",
    "url": "https://linkedin.com/feed/update/urn:li:activity:7123456789",
    "postcontent": "Post content here...",
    "author_id": 42,
    "author_linkedin_id": "john-doe-123",
    "author_name": "John Doe",
    "author_headline": "Software Engineer at TechCorp",
    "author_connection_degree": "1st",
    "reactions": 42,
    "comments": 5,
    "reposts": 3,
    "engagement": 50,
    "timestamp": "2025-01-15T10:30:00Z"
  }
]

Connection Management

POST `/api/v1/connections/simple`

Send a simple connection request without a message.

Request Body:

{
  "profile_identifier": "john-doe-123",
  "server_call": false
}

Parameters:

• profile_identifier (string) - LinkedIn profile ID (e.g., 'john-doe-123') or full profile URL
• server_call (boolean) - Execution mode (false: proxy, true: server)

Response:

{
  "success": true
}

POST `/api/v1/connections/with-message`

Send a connection request with a personalized message.

Request Body:

{
  "profile_identifier": "john-doe-123",
  "message": "Hi John, I'd like to connect!",
  "server_call": false
}

Parameters:

• profile_identifier (string) - LinkedIn profile ID or full profile URL
• message (string) - Custom message to include with connection request
• server_call (boolean) - Execution mode (false: proxy, true: server)

Response:

{
  "success": true
}

Messaging

POST `/api/v1/messages/send`

Send a direct message to a LinkedIn profile.

Request Body:

{
  "profile_identifier": "john-doe-123",
  "message_text": "Hello! I saw your profile...",
  "server_call": false
}

Parameters:

• profile_identifier (string) - LinkedIn profile ID or full profile URL
• message_text (string) - Message text to send
• server_call (boolean) - Execution mode (false: proxy, true: server)

Response:

{
  "success": true
}

POST `/api/v1/messages/my-id`

Get your authenticated user's LinkedIn profile ID.

Request Body:

{
  "server_call": false
}

Response:

{
  "success": true,
  "profile_id": "john-doe-123"
}

Profile Operations

POST `/api/v1/profiles/scrape`

Extract complete profile data including identity, contact info, about section, and skills.

Request Body:

{
  "profile_id": "john-doe-123",
  "server_call": false
}

Parameters:

• profile_id (string) - LinkedIn profile ID or full profile URL
• server_call (boolean) - Execution mode (false: proxy, true: server)

POST `/api/v1/profiles/experiences`

Scrape work experience history from a LinkedIn profile.

Request Body:

{
  "profile_id": "john-doe-123",
  "server_call": false
}

POST `/api/v1/profiles/identity`

Get identity data (name, headline, location, connection degree, follower count).

Request Body:

{
  "profile_id": "john-doe-123",
  "server_call": false
}

POST `/api/v1/posts/profile-posts`

Fetch posts published by a specific LinkedIn profile.

Request Body:

{
  "profile_id": "john-doe-123",
  "count": 10,
  "server_call": false
}

Parameters:

• profile_id (string) - LinkedIn profile ID or URL
• count (integer) - Number of posts to fetch (default: 10)
• server_call (boolean) - Execution mode

Comment Operations

POST `/api/v1/posts/get-commenters`

Fetch commenters and comments from a LinkedIn post with pagination support.

Request Body:

{
  "post_url": "https://linkedin.com/feed/update/urn:li:activity:7123456789",
  "count": -1,
  "num_replies": 0,
  "server_call": false
}

Parameters:

• post_url (string) - LinkedIn post URL or activity URN
• count (integer) - Number of comments to fetch (-1 for all, default: -1)
• num_replies (integer) - Number of replies to fetch per comment (default: 0)
• server_call (boolean) - Execution mode

POST `/api/v1/posts/post-comment`

POST `/api/v1/posts/reply-to-comment`

Reply to an existing comment on a LinkedIn post.

Request Body:

{
  "comment_urn": "urn:li:fsd_comment:(7123456789,urn:li:activity:7123456789)",
  "reply_text": "Thanks for sharing!",
  "server_call": false
}

Parameters:

• comment_urn (string) - Comment URN (provided by get-commenters endpoint in commentUrn field)
• reply_text (string) - Reply text to post
• server_call (boolean) - Execution mode

Response:

{
  "success": true
}

Reactions

POST `/api/v1/posts/get-reactions`

Fetch all reactions (likes) for a LinkedIn post with detailed reactor information.

Headers:

X-API-Key: LKG_your_api_key_here
Content-Type: application/json

Request Body:

{
  "post_url": "https://linkedin.com/feed/update/urn:li:activity:7123456789",
  "count": -1,
  "server_call": false,
  "min_delay": 0.5,
  "max_delay": 1.5
}

Parameters:

Parameter	Type	Description
`post_url`	string	LinkedIn post URL or activity URN
`count`	integer	Number of reactions to fetch (-1 for all, default: 10)
`server_call`	boolean	Execution mode (false: proxy, true: server)
`min_delay`	float	Min delay between pagination requests (seconds, default: 0.5)
`max_delay`	float	Max delay between pagination requests (seconds, default: 1.5)

Response:

{
  "data": [
    {
      "userId": "ACoAAD7-6OkBzHtPyDUD0wH2GSITJntEoxFm8K0",
      "userName": "John Doe",
      "userTitle": "Software Engineer at TechCorp",
      "connectionLevel": "1st",
      "reactionType": "LIKE"
    },
    {
      "userId": "ACoAACXyz123...",
      "userName": "Jane Smith",
      "userTitle": "Product Manager",
      "connectionLevel": "2nd",
      "reactionType": "PRAISE"
    }
  ]
}

💡 Reaction Types

LinkedIn supports multiple reaction types:

• LIKE - Standard like reaction
• PRAISE - Celebrate/hands clapping
• APPRECIATION - Love/heart
• EMPATHY - Care/hug
• INTEREST - Curious/lightbulb
• ENTERTAINMENT - Funny/laughing

User Comments

POST `/api/v1/profile/comments`

Fetch all comments made by a specific user profile with full context including posts and parent comments.

Headers:

X-API-Key: LKG_your_api_key_here
Content-Type: application/json

Request Body:

{
  "profile_id": "john-doe-123",
  "count": 20,
  "server_call": false,
  "min_delay": 0.5,
  "max_delay": 1.5
}

Parameters:

Parameter	Type	Description
`profile_id`	string	LinkedIn profile ID or full profile URL
`count`	integer	Number of comments to fetch (-1 for all, max: 200)
`server_call`	boolean	Execution mode (false: proxy, true: server)
`min_delay`	float	Min delay between pagination requests (seconds, default: 0.5)
`max_delay`	float	Max delay between pagination requests (seconds, default: 1.5)

Response:

{
  "data": [
    {
      "commentText": "Great insights! Thanks for sharing.",
      "commentId": "urn:li:comment:(7123456789,urn:li:activity:7123456780)",
      "postText": "Here's my latest article on AI...",
      "postUrl": "https://linkedin.com/feed/update/urn:li:activity:7123456780",
      "parentCommentText": null,
      "parentCommentId": null,
      "parentCommenterName": null,
      "parentCommenterHeadline": null,
      "parentCommenterProfileId": null,
      "isReply": false,
      "replyToUserCommentText": null,
      "replyToUserCommentId": null
    },
    {
      "commentText": "I agree with your point about automation.",
      "commentId": "urn:li:comment:(7123456790,urn:li:activity:7123456781)",
      "postText": "Discussion about the future of work...",
      "postUrl": "https://linkedin.com/feed/update/urn:li:activity:7123456781",
      "parentCommentText": "Automation is changing everything.",
      "parentCommentId": "urn:li:comment:(7123456788,urn:li:activity:7123456781)",
      "parentCommenterName": "Jane Smith",
      "parentCommenterHeadline": "Tech Lead at AI Corp",
      "parentCommenterProfileId": "ACoAACXyz123...",
      "isReply": true,
      "replyToUserCommentText": null,
      "replyToUserCommentId": null
    }
  ]
}

💡 Comment Context

This endpoint provides rich context for each comment:

• Root Comments: Direct comments on posts (isReply: false)
• Reply Comments: Replies to other comments (isReply: true)
• Post Context: Full post text and URL for each comment
• Parent Details: When it's a reply, includes parent comment and commenter info
• Hard Limit: Maximum 200 comments to prevent excessive API calls

📖 Interactive Documentation

Once the server is running, visit the interactive API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🚢 Deployment

Production Deployment Options

1. Docker Compose (Recommended)

• Complete setup in deployment/ folder
• Includes PostgreSQL, backend, health checks
• One-command deployment
• See deployment/README.md

2. VPS/Self-Hosted

• Ubuntu/Debian server
• Nginx reverse proxy
• Let's Encrypt SSL certificates
• Systemd service management

3. Cloud Platforms

• Heroku, Railway, Render
• One-click deployment
• Managed PostgreSQL
• Auto-scaling

Environment Variables

Key environment variables (see backend/.env.example):

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=LinkedinGateway

# API
API_HOST=0.0.0.0
API_PORT=8000

# JWT
JWT_SECRET_KEY=your_secret_key
JWT_ALGORITHM=HS256
JWT_EXPIRATION_MINUTES=10080

# LinkedIn OAuth
LINKEDIN_CLIENT_ID=your_client_id
LINKEDIN_CLIENT_SECRET=your_client_secret
LINKEDIN_REDIRECT_URI=https://your-domain.com/auth/user/callback

# CORS
CORS_ORIGINS=*

# Rate Limiting
DEFAULT_RATE_LIMIT=100
DEFAULT_RATE_WINDOW=3600

HTTPS Setup

⚠️ HTTPS Required

LinkedIn OAuth requires HTTPS. Available options:

• Cloudflare Tunnel (Free, recommended for development)
• Ngrok (Free tier available)
• Nginx + Let's Encrypt (Self-hosted production)
• Cloud Platform SSL (Managed)

See backend/HTTPS_TUNNELING_GUIDE.md for detailed setup instructions.

📊 Monitoring & Logging

Health Checks

Endpoint	Description
`GET /health`	API health status
`GET /health/db`	Database connection health
`GET /api/ws/status`	WebSocket connection status

Logging

Logs are written to:

Console: Structured JSON logs
File: backend/logs/ (if configured)
Docker: docker-compose logs -f backend

Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL

🛠️ Technology Stack

Backend

• FastAPI (Python 3.11+)
• PostgreSQL 15
• SQLAlchemy 2.0 (async)
• Alembic (migrations)
• JWT + LinkedIn OAuth 2.0
• HTTPX (async)

Chrome Extension

• Manifest V3
• Webpack 5
• JavaScript (ES6+)
• HTML5, CSS3
• Chrome Extension APIs
• WebSocket API

Infrastructure

• Docker & Docker Compose
• Nginx (reverse proxy)
• Uvicorn with Gunicorn
• Health check endpoints
• Structured logging

⚠️ Important Notes

⚖️ LinkedIn Terms of Service

This tool interacts with LinkedIn's internal APIs. Users are responsible for:

• Complying with LinkedIn's Terms of Service
• Respecting rate limits and usage policies
• Not engaging in spam or abusive behavior
• Understanding potential account risks

Rate Limiting

Default: 100 requests per hour per API key
Configurable: Per user settings
Response: 429 status code when exceeded
Retry: Automatic retry with exponential backoff recommended

Session Management

LinkedIn sessions expire periodically
Server mode requires session refresh
Proxy mode uses browser's active session
Automatic session refresh on 401/403 errors

🆘 Support & Resources

📦 GitHub Repository

Access source code, report issues, and contribute

📖 Interactive API Docs

Swagger UI with live testing capabilities

🏠 AInnovate.tech

Visit our main website for more AI tools and solutions

🛠️ More Tools

Explore our collection of free AI tools and demos

🎯 Overview

Dual Execution Architecture

✅ Key Features

Complete LinkedIn API Coverage

Dual Execution Modes

Enterprise-Ready

Production Deployment

🏗️ Architecture

Execution Modes

1. Server-Side Execution (server_call=true)

2. Browser Proxy Mode (server_call=false)

🚀 Quick Start

Prerequisites

Option 1: Docker Deployment (Recommended)

Option 2: Local Development

Chrome Extension Setup

🔐 Authentication

API Key Authentication

1. Header Authentication (Recommended)

2. Body Authentication

OAuth 2.0 Flow

📚 API Reference

Feed Operations

POST /api/v1/feed/posts

Connection Management

POST /api/v1/connections/simple

POST /api/v1/connections/with-message

Messaging

POST /api/v1/messages/send

POST /api/v1/messages/my-id

Profile Operations

POST /api/v1/profiles/scrape

POST /api/v1/profiles/experiences

POST /api/v1/profiles/identity

POST /api/v1/posts/profile-posts

Comment Operations

POST /api/v1/posts/get-commenters

POST /api/v1/posts/post-comment

POST /api/v1/posts/reply-to-comment

Reactions

POST /api/v1/posts/get-reactions

User Comments

POST /api/v1/profile/comments

🚢 Deployment

Production Deployment Options

1. Docker Compose (Recommended)

2. VPS/Self-Hosted

3. Cloud Platforms

Environment Variables

HTTPS Setup

📊 Monitoring & Logging

Health Checks

Logging

🛠️ Technology Stack

Backend

Chrome Extension

Infrastructure

⚠️ Important Notes

Rate Limiting

Session Management

🆘 Support & Resources

📦 GitHub Repository

📖 Interactive API Docs

🏠 AInnovate.tech

🛠️ More Tools

1. Server-Side Execution (`server_call=true`)

2. Browser Proxy Mode (`server_call=false`)

POST `/api/v1/feed/posts`

POST `/api/v1/connections/simple`

POST `/api/v1/connections/with-message`

POST `/api/v1/messages/send`

POST `/api/v1/messages/my-id`

POST `/api/v1/profiles/scrape`

POST `/api/v1/profiles/experiences`

POST `/api/v1/profiles/identity`

POST `/api/v1/posts/profile-posts`

POST `/api/v1/posts/get-commenters`

POST `/api/v1/posts/post-comment`

POST `/api/v1/posts/reply-to-comment`

POST `/api/v1/posts/get-reactions`

POST `/api/v1/profile/comments`