Getting Started

Authentication

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

Authenticated JSON-RPC methods on the SocialCRM MCP API require a valid API key passed as a Bearer token.

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

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

Include the key in the Authorization header for authenticated requests (tools/list and tools/call):

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Example:

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

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