> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truedy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate to the Truedy API with API keys or JWT

# 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](https://app.truedy.ai).
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.

| Code  | Meaning                                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Bad request — invalid parameters or body                                                                                                           |
| `401` | Unauthorized — missing or invalid API key; use the `Authorization: Bearer <key>` header                                                            |
| `402` | Payment required — trial not started, trial expired, subscription inactive, or insufficient credits; see `error.details.redirect_url` and `reason` |
| `403` | Forbidden — key valid but not allowed (e.g. IP not whitelisted)                                                                                    |
| `404` | Not found — resource or ID does not exist                                                                                                          |
| `422` | Unprocessable entity — validation failed (e.g. invalid E.164, missing required field)                                                              |
| `429` | Rate limit exceeded; check `Retry-After` and limit headers                                                                                         |
| `500` | Internal server error                                                                                                                              |

Errors follow this shape:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key",
    "details": {}
  },
  "meta": {
    "request_id": "uuid",
    "ts": "2026-02-04T12:00:00Z"
  }
}
```