Skip to main content

​
Authentication

The Truedy API supports two authentication methods depending on your use case.

​
Public API (API key)

Use API keys for server-to-server integration and the Public API at base path /api/public/v1.

​
Sending your API key

Send your API key in the Authorization header as a Bearer token: 
Authorization: Bearer truedy_YOUR_API_KEY
Use this single header for all Public API requests. The API playground and docs ask for your key once in Authorization.

​
Creating an API key

  1. Log in to the Truedy Dashboard.
  2. Go to Settings → API Keys.
  3. Click Create API Key, give it a name, and copy the key (shown once).

​
Security

  • Do not commit API keys to source control or expose them in client-side code.
  • Use IP whitelisting and rate limits per key when possible.
  • Keys can be revoked at any time from the dashboard.

​
Frontend API (JWT)

The frontend API at /api/v1 uses Clerk JWT tokens for browser-based apps. Use the Clerk SDK to obtain a session token and send it in the Authorization header.

​
Error responses

All Public API endpoints may return these status codes. The API reference documents them for every endpoint.
CodeMeaning
400Bad request — invalid parameters or body
401Unauthorized — missing or invalid API key; use the Authorization: Bearer <key> header
403Forbidden — key valid but not allowed (e.g. IP not whitelisted)
404Not found — resource or ID does not exist
422Unprocessable entity — validation failed (e.g. invalid E.164, missing required field)
429Rate limit exceeded; check Retry-After and limit headers
500Internal server error
Errors follow this shape: 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key",
    "details": {}
  },
  "meta": {
    "request_id": "uuid",
    "ts": "2026-02-04T12:00:00Z"
  }
}