Authentication

Every endpoint except /v1/openapi.json and /v1/sample/news requires an API key.

Scheme

Bearer token in the Authorization header:

Authorization: Bearer <your-api-key>

The OpenAPI schema declares this as ApiKeyAuth — an HTTP bearer scheme whose bearerFormat is The Neural Ledger API key. There is no OAuth flow, no key rotation endpoint, and no query-string key parameter on the REST API.

curl -sS "https://theneuralledger.com/v1/me" \
  -H "Authorization: Bearer $TNL_API_KEY"

Keys are secrets

A key carries your full plan allowance. Keep it server-side. Do not ship it in a browser bundle, a mobile app, or a public repository — anything shipped to a client is readable by that client.

Checking a key

/v1/me is the canonical check. It returns the key metadata, the resolved plan, and the current month's usage:

{
  "key": { "id": "…", "name": "…", "prefix": "…" },
  "plan": { "…": "plan fields" },
  "usage": {
    "month": "2026-07",
    "calls": 1284,
    "remaining": 8716,
    "monthlyLimit": 10000,
    "resetAt": "2026-08-01T00:00:00.000Z"
  }
}

monthlyLimit and remaining are null on plans with no fixed cap.

Failure modes

Status	Meaning	What to do
401	Missing or invalid API key	Check the header spelling and that the key is active. The header is Authorization, and the value must start with Bearer .
429	Monthly call limit exceeded	You have spent your allowance. It resets at usage.resetAt. Upgrade on the plans page.

A 401 is not rate limiting and a 429 is not an auth problem — they need different handling. See Errors & rate limits.

MCP authentication is different

The hosted MCP server does not use API keys. It authenticates with OAuth 2.0 against the TNL identity provider and requires the tnl:read scope. See Connecting to MCP.