Skip to main content

Authentication

All PlexMCP API requests require authentication. This guide covers how to authenticate your requests.

API Keys​

The primary authentication method is via API keys. Each key:

  • Is tied to your organization
  • Has specific permissions
  • Can be revoked instantly
  • Tracks usage independently

Using Your API Key​

Include your API key in the Authorization header:

curl -X GET https://api.plexmcp.com/v1/mcps \
  -H "Authorization: Bearer YOUR_API_KEY"

Header Format​

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxx
  • Prefix: Always Bearer (with space)
  • Key format: Starts with pk_live_ (production) or pk_test_ (test)

Key Types​

Live Keys (pk_live_)​

Production keys for real API calls:

  • Count toward usage limits
  • Use in production applications
  • Never expose in client-side code

Test Keys (pk_test_)​

For development and testing:

  • Limited to test MCPs
  • Don't count toward billing
  • Safe for development environments

Getting Your API Key​

  1. Log in to dashboard.plexmcp.com
  2. Navigate to API Keys
  3. Click Create API Key
  4. Configure name, expiration, and permissions
  5. Copy the key immediately (shown only once)

Key Permissions​

Each key can be scoped to specific MCPs:

All MCPs​

{
  "permissions": {
    "mcps": "*"
  }
}

Access all current and future MCPs.

Specific MCPs​

{
  "permissions": {
    "mcps": ["mcp_123", "mcp_456"]
  }
}

Access only listed MCPs.

Authentication Errors​

401 Unauthorized​

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Causes:

  • Missing Authorization header
  • Invalid API key format
  • Revoked API key
  • Expired API key

403 Forbidden​

{
  "success": false,
  "error": {
    "code": "forbidden",
    "message": "API key does not have permission for this resource"
  }
}

Causes:

  • Key doesn't have access to requested MCP
  • Key is test mode but accessing live resources
  • Organization-level restriction

Security Best Practices​

Never Expose Keys in Client Code​

// BAD - Don't do this!
const apiKey = "pk_live_xxxxx";

// GOOD - Use environment variables
const apiKey = process.env.PLEXMCP_API_KEY;

Use Environment Variables​

# .env file (not committed to git)
PLEXMCP_API_KEY=pk_live_xxxxx

# In your code
const apiKey = process.env.PLEXMCP_API_KEY;

Rotate Keys Regularly​

  1. Create a new key
  2. Update your applications
  3. Verify everything works
  4. Revoke the old key

Use Minimal Permissions​

Only grant access to MCPs the key actually needs.

Set Expiration Dates​

For temporary access or contractors:

  • Short-term: 30 days
  • Regular rotation: 90 days
  • Long-term: 1 year max

Monitor Key Usage​

Check the dashboard for:

  • Unusual request patterns
  • Unexpected locations
  • Error rate spikes

Code Examples​

Node.js / TypeScript​

import { PlexMCP } from '@plexmcp/sdk';

const client = new PlexMCP({
  apiKey: process.env.PLEXMCP_API_KEY,
});

Python​

import os
from plexmcp import PlexMCP

client = PlexMCP(api_key=os.environ["PLEXMCP_API_KEY"])

cURL​

export PLEXMCP_API_KEY="pk_live_xxxxx"

curl -X GET https://api.plexmcp.com/v1/mcps \
  -H "Authorization: Bearer $PLEXMCP_API_KEY"

Go​

package main

import (
    "os"
    "github.com/plexmcp/plexmcp-go"
)

func main() {
    client := plexmcp.NewClient(os.Getenv("PLEXMCP_API_KEY"))
}

Troubleshooting​

"Invalid API Key" Error​

  1. Verify the complete key was copied
  2. Check for trailing whitespace
  3. Ensure Bearer prefix is present
  4. Verify the key hasn't been revoked

Key Works in cURL but Not in Code​

  1. Check environment variable is set
  2. Verify no extra characters in key
  3. Ensure proper header formatting
  4. Check for HTTPS requirement

Key Suddenly Stopped Working​

  1. Check if key was revoked
  2. Verify key hasn't expired
  3. Check usage limits
  4. Review recent activity for security issues