Skip to content

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.

bash
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:

json
{
  "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 ​

StatusMeaningWhat to do
401Missing or invalid API keyCheck the header spelling and that the key is active. The header is Authorization, and the value must start with Bearer .
429Monthly call limit exceededYou 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.

The Neural Ledger API