API Authentication

API Key Authentication Guide

Overview

The Schema.org MCP server includes built-in API key authentication for secure external access. All requests to protected endpoints require a valid API key.

Quick Start

1. Get Your API Key

On first server startup, a default API key is automatically generated and logged:

Default API key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

This key is stored in .api-keys.json in the project directory.

2. Use the API Key

Include the API key in your requests using one of these methods:

Authorization Header (Recommended):

curl -H "Authorization: Bearer sk_your_api_key" \
  https://json-ld-schema-mcp.serptransformer.com/sse

X-API-Key Header:

curl -H "X-API-Key: sk_your_api_key" \
  https://json-ld-schema-mcp.serptransformer.com/sse

Query Parameter:

curl "https://json-ld-schema-mcp.serptransformer.com/sse?api_key=sk_your_api_key"

API Key Format

API keys follow the format: sk_ followed by 64 random hexadecimal characters.

Example: sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2

Configuration

Environment Variables

VariableDefaultPurpose
REQUIRE_AUTHtrueEnable/disable API key authentication
API_KEYS_CONFIG.api-keys.jsonPath to API keys configuration file

Disable Authentication (Development Only)

REQUIRE_AUTH=false USE_SSE=true SSE_PORT=3000 node dist/index.js

API Keys Configuration File

The API keys are stored in .api-keys.json:

{
  "sk_abcdef1234567890...": {
    "key": "sk_abcdef1234567890...",
    "name": "default-key",
    "enabled": true,
    "createdAt": "2025-12-23T07:00:00.000Z",
    "lastUsed": "2025-12-23T07:05:00.000Z",
    "rateLimit": null
  },
  "sk_fedcba0987654321...": {
    "key": "sk_fedcba0987654321...",
    "name": "production-key",
    "enabled": true,
    "createdAt": "2025-12-23T06:00:00.000Z",
    "lastUsed": "2025-12-23T07:04:00.000Z",
    "rateLimit": 1000
  }
}

File Permissions: The file is created with mode 0600 (read/write for owner only). Keep this secure!

Managing API Keys

View API Keys

List all API keys (requires authentication):

curl -H "Authorization: Bearer sk_your_api_key" \
  https://json-ld-schema-mcp.serptransformer.com/api-keys

Response:

{
  "keys": [
    {
      "name": "default-key",
      "enabled": true,
      "createdAt": "2025-12-23T07:00:00.000Z",
      "lastUsed": "2025-12-23T07:05:00.000Z"
    },
    {
      "name": "production-key",
      "enabled": true,
      "createdAt": "2025-12-23T06:00:00.000Z",
      "lastUsed": "2025-12-23T07:04:00.000Z"
    }
  ]
}

Generate New Keys

Edit .api-keys.json and add a new entry:

{
  "sk_newkey1234567890abcdef...": {
    "key": "sk_newkey1234567890abcdef...",
    "name": "my-app-key",
    "enabled": true,
    "createdAt": "2025-12-23T07:10:00.000Z",
    "rateLimit": 500
  }
}

Or use a Node.js script:

import { ApiKeyManager } from './dist/auth.js';
 
const manager = new ApiKeyManager();
const newKey = manager.addKey('my-app-key', 500); // 500 requests/hour
console.log('New API Key:', newKey);

Revoke a Key

Set "enabled": false in .api-keys.json:

{
  "sk_oldkey1234567890abcdef...": {
    "key": "sk_oldkey1234567890abcdef...",
    "name": "old-key",
    "enabled": false,
    "createdAt": "2025-12-23T06:00:00.000Z"
  }
}

Revoked keys will immediately be rejected for all requests.

Protected Endpoints

The following endpoints require API key authentication:

  • GET /sse - SSE connection endpoint
  • POST /messages - Message POST endpoint
  • GET /api-keys - List API keys

Public Endpoints

These endpoints do NOT require authentication:

  • GET /health - Health check

Error Responses

Missing or Invalid API Key

Status Code: 401 Unauthorized

{
  "error": "Unauthorized: Invalid or missing API key"
}

Malformed Request

Status Code: 400 Bad Request

{
  "error": "Invalid JSON"
}

Not Found

Status Code: 404 Not Found

{
  "error": "Not found"
}

Security Best Practices

  1. Keep Keys Secure

    • Never commit .api-keys.json to version control
    • Use environment variables or secure vaults for production
    • Restrict file permissions to 0600

  2. Rotate Keys Regularly

    • Generate new keys periodically
    • Revoke old keys after rotation
    • Track key creation and last usage dates

  3. Use Unique Keys Per Application

    • Create separate keys for each client/application
    • Easier to revoke if a key is compromised
    • Better audit trail

  4. Monitor Key Usage

    • Check lastUsed timestamps regularly
    • Investigate unused keys
    • Remove keys that haven't been used in 90 days

  5. HTTPS Only

    • Always use HTTPS for API requests
    • Never send API keys over unencrypted connections
    • Use TLS 1.2 or higher

Integration Examples

Node.js/TypeScript

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 
const apiKey = process.env.SCHEMA_ORG_API_KEY;
 
const transport = new SSEClientTransport({
  url: 'https://json-ld-schema-mcp.serptransformer.com/sse',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
  },
});
 
const client = new Client({
  name: 'schema-org-client',
  version: '1.0.0',
}, {
  capabilities: {},
});
 
await client.connect(transport);

Python

import requests
from sseclient import SSEClient
import os
 
api_key = os.getenv('SCHEMA_ORG_API_KEY')
headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json',
}
 
url = 'https://json-ld-schema-mcp.serptransformer.com/sse'
client = SSEClient(url, headers=headers)
 
for event in client:
    if event.event == 'message':
        print(f"Received: {event.data}")

cURL

# Using environment variable
API_KEY="sk_your_api_key"
 
# SSE connection
curl -H "Authorization: Bearer $API_KEY" \
  https://json-ld-schema-mcp.serptransformer.com/sse
 
# List API keys
curl -H "Authorization: Bearer $API_KEY" \
  https://json-ld-schema-mcp.serptransformer.com/api-keys
 
# Health check (no auth required)
curl https://json-ld-schema-mcp.serptransformer.com/health

Troubleshooting

"Unauthorized: Invalid or missing API key"

  1. Verify the API key is correct
  2. Check the key is enabled in .api-keys.json
  3. Ensure the key is included in the request headers
  4. Verify HTTPS is being used

API Key Not Working After Update

  1. Restart the server: sudo systemctl restart schema-org-mcp
  2. Check .api-keys.json is valid JSON
  3. Verify file permissions: ls -la .api-keys.json
  4. Check server logs: sudo journalctl -u schema-org-mcp -f

Lost Default API Key

If you lose the default API key:

  1. Stop the server: sudo systemctl stop schema-org-mcp
  2. Delete .api-keys.json
  3. Start the server: sudo systemctl start schema-org-mcp
  4. A new default key will be generated and logged

Rate Limiting (Future)

The API key structure supports per-key rate limiting (currently not enforced):

{
  "sk_key...": {
    "name": "limited-key",
    "rateLimit": 100
  }
}

Rate limiting will be implemented in a future release.

Complete SetupAPI Endpoints