API Authentication

The Plugged.in API uses Bearer token authentication to secure endpoints and identify users. This guide covers how to obtain and use API keys.

Quick Start

Get API Key

Navigate to API Keys in your dashboard

Create New Key

Click “Generate New API Key” and save it securely

Use in Requests

Include the key in your Authorization header:

Authorization: Bearer YOUR_API_KEY

Authentication Methods

Bearer Token (Recommended)

The primary authentication method for the Plugged.in API.

curl "https://plugged.in/api/servers" \
  -H "Authorization: Bearer pk_live_abc123..."

OAuth 2.0

For third-party applications that need to access user data on their behalf.

Authorization Flow

Redirect to Authorization

https://plugged.in/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_CALLBACK_URL&
  response_type=code&
  scope=read:servers write:servers

User Approves

User logs in and approves the requested permissions

Receive Authorization Code

GET YOUR_CALLBACK_URL?code=auth_code_123

Exchange for Access Token

curl -X POST "https://plugged.in/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "auth_code_123",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "YOUR_CALLBACK_URL"
  }'

Token Response:

{
  "access_token": "at_abc123...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_xyz789...",
  "scope": "read:servers write:servers"
}

Session Authentication

For browser-based applications using cookies.

// Login via form submission
const response = await fetch('/api/auth/login', {
  method: 'POST',
  credentials: 'include', // Important: includes cookies
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password'
  })
});

// Subsequent requests include session cookie automatically
const servers = await fetch('/api/servers', {
  credentials: 'include'
});

API Key Management

Creating API Keys

API keys can be created through the dashboard or API.

Via Dashboard

Navigate to API Keys
Click “Generate New API Key”
Set optional expiration date
Add description for reference
Copy and save the key securely

Via API

POST /api/auth/keys

curl -X POST "https://plugged.in/api/auth/keys" \
  -H "Authorization: Bearer YOUR_EXISTING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "expires_at": "2025-12-31T23:59:59Z",
    "scopes": ["read:servers", "write:servers"]
  }'

Key Formats

API keys follow a consistent format for easy identification:

Environment	Prefix	Example
Production	`pk_live_`	`pk_live_abc123...`
Test	`pk_test_`	`pk_test_xyz789...`
Secret	`sk_live_`	`sk_live_def456...`

Key Rotation

Regular key rotation is recommended for security. Rotate keys:

Every 90 days for production environments
Immediately if a key is compromised
When team members leave

Rotation Process

Generate New Key

Create a new API key while keeping the old one active

Update Applications

Deploy your applications with the new key

Verify

Ensure all systems are using the new key

Revoke Old Key

Delete the old key from the dashboard

Revoking Keys

DELETE /api/auth/keys/{key_id}

curl -X DELETE "https://plugged.in/api/auth/keys/key_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Permissions & Scopes

API keys can have different permission scopes:

Available Scopes

Scope	Description
`read:servers`	Read MCP server configurations
`write:servers`	Create and modify MCP servers
`delete:servers`	Remove MCP servers
`read:documents`	Access document library
`write:documents`	Upload and modify documents
`read:profile`	View profile information
`write:profile`	Update profile settings
`read:collections`	View collections
`write:collections`	Create and modify collections
`admin`	Full administrative access

Scope Examples

// Limited scope key - read only
const readOnlyClient = new PluggedinClient({
  apiKey: 'pk_live_readonly...',
  scopes: ['read:servers', 'read:documents']
});

// Full access key
const adminClient = new PluggedinClient({
  apiKey: 'pk_live_admin...',
  scopes: ['admin']
});

Security Best Practices

Storage

Recommended for server applications

# .env file
PLUGGEDIN_API_KEY=pk_live_abc123...

const apiKey = process.env.PLUGGEDIN_API_KEY;

Security Guidelines

Never Expose Keys in Code

Use HTTPS Only

Implement Rate Limiting

Respect rate limits to avoid key suspension:

import { RateLimiter } from 'limiter';

const limiter = new RateLimiter({
  tokensPerInterval: 60,
  interval: 'minute'
});

await limiter.removeTokens(1);
// Make API request

Monitor Key Usage

Track API key usage for unusual patterns:

// Log all API requests
client.on('request', (request) => {
  logger.info('API Request', {
    endpoint: request.url,
    timestamp: new Date()
  });
});

Error Handling

Common Authentication Errors

Error Code	Description	Solution
`401 UNAUTHORIZED`	Missing or invalid API key	Check key is included in header
`403 FORBIDDEN`	Key lacks required scope	Generate key with correct permissions
`429 RATE_LIMITED`	Too many requests	Implement exponential backoff
`410 GONE`	API key revoked	Generate a new API key

Error Response Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key provided",
    "details": {
      "key_prefix": "pk_test_",
      "hint": "Ensure you're using a production key for this environment"
    }
  }
}

Handling Errors

try {
  const response = await fetch('https://plugged.in/api/servers', {
    headers: {
      'Authorization': 'Bearer ' + apiKey
    }
  });

  if (!response.ok) {
    const error = await response.json();

    switch (error.error.code) {
      case 'UNAUTHORIZED':
        // Refresh token or prompt for new key
        break;
      case 'RATE_LIMITED':
        // Wait and retry with exponential backoff
        await sleep(Math.pow(2, retryCount) * 1000);
        break;
      default:
        throw new Error(error.error.message);
    }
  }
} catch (error) {
  console.error('API request failed:', error);
}

Testing

Test API Keys

Use test API keys for development and testing:

const client = new PluggedinClient({
  apiKey: process.env.NODE_ENV === 'production'
    ? 'pk_live_abc123...'
    : 'pk_test_xyz789...'
});

Mock Authentication

For unit tests, mock the authentication:

// Jest example
jest.mock('@pluggedin/sdk', () => ({
  PluggedinClient: jest.fn().mockImplementation(() => ({
    servers: {
      list: jest.fn().mockResolvedValue([
        { id: '1', name: 'Test Server' }
      ])
    }
  }))
}));

Migration Guide

From API v1 to v2

If you’re migrating from an older API version:

Update Authentication Header

// Old (v1)
headers: { 'X-API-Key': apiKey }

// New (v2)
headers: { 'Authorization': 'Bearer ' + apiKey }

Update Endpoints

// Old (v1)
/api/v1/servers

// New (v2)
/api/servers

Handle New Response Format

Responses now include consistent error objects and pagination

Support

For authentication issues or questions:

Documentation: API Reference
Status Page: status.plugged.in
Support Email: api-support@plugged.in
GitHub Issues: Report issues

API Documentation

Authentication Guide

API Authentication

Quick Start

Authentication Methods

Bearer Token (Recommended)

OAuth 2.0

Authorization Flow

Session Authentication

API Key Management

Creating API Keys

Via Dashboard

Via API

Key Formats

Key Rotation

Rotation Process

Revoking Keys

Permissions & Scopes

Available Scopes

Scope Examples

Security Best Practices

Storage

Security Guidelines

Error Handling

Common Authentication Errors

Error Response Example

Handling Errors

Testing

Test API Keys

Mock Authentication

Migration Guide

From API v1 to v2

Support

API Documentation

​API Authentication

​Quick Start

​Authentication Methods

​Bearer Token (Recommended)

​OAuth 2.0

​Authorization Flow

​Session Authentication

​API Key Management

​Creating API Keys

​Via Dashboard

​Via API

​Key Formats

​Key Rotation

​Rotation Process

​Revoking Keys

​Permissions & Scopes

​Available Scopes

​Scope Examples

​Security Best Practices

​Storage

​Security Guidelines

​Error Handling

​Common Authentication Errors

​Error Response Example

​Handling Errors

​Testing

​Test API Keys

​Mock Authentication

​Migration Guide

​From API v1 to v2

​Support

API Authentication

Quick Start

Authentication Methods

Bearer Token (Recommended)

OAuth 2.0

Authorization Flow

Session Authentication

API Key Management

Creating API Keys

Via Dashboard

Via API

Key Formats

Key Rotation

Rotation Process

Revoking Keys

Permissions & Scopes

Available Scopes

Scope Examples

Security Best Practices

Storage

Security Guidelines

Error Handling

Common Authentication Errors

Error Response Example

Handling Errors

Testing

Test API Keys

Mock Authentication

Migration Guide

From API v1 to v2

Support