Authentication

Used exclusively by CardMind satellite projects (cardmind-social, cardmind-video, cardmind-pages) to call the API hub without consuming rate-limit quota. If this header is present and matches the server-side secret, all rate limits and tier checks are bypassed.

curl "https://api.cardmind.app/api/signals/recent" \
  -H "x-internal-secret: <INTERNAL_API_SECRET>"

This method is not available to external developers. The secret is never exposed in responses or logs.

The standard method for external developers. Generate an API key at cardmind.app/settings and pass it as a Bearer token in the Authorization header on every request.

API Key Format

All API keys are prefixed with cm_live_. Never share your key — it grants full access to your account's quota.

Example request

curl "https://api.cardmind.app/api/cards/search?q=lightning+bolt" \
  -H "Authorization: Bearer cm_live_YOUR_KEY"

Generating your key

1. Sign up at cardmind.app
2. Navigate to Settings → API Keys
3. Click “Generate new key” and copy the key immediately — it is only shown once

MCP clients (Claude Desktop, ChatGPT, and compatible agents) authenticate via OAuth2 when connecting to https://api.cardmind.app/mcp. The OAuth2 token is validated server-side and mapped to your CardMind account. This method requires a Premium subscription.

See the MCP Protocol → page for setup instructions for Claude Desktop and ChatGPT.

Error Responses

All authentication failures return a consistent JSON envelope. The code field identifies the error type programmatically.

401 Unauthorized — response shape

{
  "data": null,
  "error": {
    "message": "Invalid or missing API key",
    "code": "UNAUTHORIZED"
  }
}

403 Forbidden — premium-only endpoint

{
  "data": null,
  "error": {
    "message": "MCP Premium required",
    "code": "PREMIUM_REQUIRED"
  }
}

Premium-only endpoints: /api/collection/value, /api/webhooks, /api/ai/analyze.

Security

• Always use HTTPS. HTTP requests are not supported.
• Never expose your API key in client-side code or public repositories.
• If your key is compromised, regenerate it immediately at cardmind.app/settings.
• Keys are stored as SHA-256 hashes on the server — CardMind cannot recover a lost key.
• Each request counts toward your monthly quota regardless of the response status.