Getting Started

Authentication

API key format, auth flow, and security best practices for the SocialCRM API.

SocialCRM supports two auth modes on the MCP API:

  • OAuth 2.1 for ChatGPT Apps connecting to https://socialcrm.com/mcp
  • Bearer API keys for generic MCP clients and direct API consumers

Public discovery endpoints (GET /mcp, GET /api/mcp-app, GET /mcp.json) and MCP lifecycle methods (initialize, notifications/initialized, ping, tools/list, resources/list, resources/read) do not require authentication.

ChatGPT App OAuth

ChatGPT discovers OAuth automatically from:

GET  /.well-known/oauth-protected-resource
GET  /.well-known/oauth-authorization-server
POST /api/oauth/register
GET  /api/oauth/authorize
POST /api/oauth/token

Authenticated tools advertise per-tool securitySchemes. When ChatGPT calls a protected tool without a linked account, SocialCRM returns a tool error with _meta["mcp/www_authenticate"] so ChatGPT can launch the OAuth linking flow.

API Key Format

API keys follow the format:

sk_live_

Keys are 40 characters long and always start with the sk_live_ prefix.

Generating a Key

  1. Log in to socialcrm.com.
  2. Navigate to Settings > API Keys.
  3. Click Create API Key.
  4. Optionally provide a description and expiration date.
  5. Copy the key immediately — it is only shown once.

The raw key is displayed only at creation time. Internally, keys are bcrypt-hashed before storage. If you lose your key, revoke it and create a new one.

Using Your Key

API-key based clients authenticate protected requests with the Authorization header:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Example:

curl -X POST https://socialcrm.com/mcp \
  -H "Authorization: Bearer sk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"list_brand_profiles","arguments":{}}}'

Key Lifecycle

Property Details
Scope Company-wide. A key grants access to all brands under the company account.
Shown once The raw key is returned only when created. It cannot be retrieved later.
Hashed storage Keys are bcrypt-hashed. The first 8 characters (prefix) are stored in plaintext for lookup.
Status Keys can be active or revoked. Revoked keys reject all requests immediately.
Expiry Keys can optionally have an expiration date. Expired keys return an error.
Last used The last_used_at timestamp is updated on every successful authentication.

Revoking a Key

In Settings > API Keys, click Revoke on any active key. Revocation is immediate and permanent — the key cannot be reactivated.

Security Best Practices

  • Store keys in environment variables or a secrets manager, never in source code.
  • Use a separate key per integration so you can revoke individually.
  • Set an expiration date for keys used in temporary or test environments.
  • Monitor last_used_at to detect unused keys and revoke them.
  • Rotate keys periodically by creating a new key, updating your integration, then revoking the old one.

Auth Error Responses

When authentication fails, the API returns a JSON-RPC error with code -32001:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32001,
    "message": "Missing Authorization header."
  }
}

Possible error messages:

Message Cause
Missing Authorization header. No Authorization header provided
Invalid API key. Key not found or does not match any active key
API key expired. Key has passed its expires_at date
Failed to validate API key. Internal error during key validation

For ChatGPT OAuth flows, unauthenticated tool calls return an MCP tool error result carrying _meta["mcp/www_authenticate"] instead of a plain JSON-RPC auth failure so ChatGPT can trigger account linking.