> For the complete documentation index, see [llms.txt](https://docs.guayaba.run/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.guayaba.run/documentation/api-reference/authentication.md).

# Authentication

All endpoints require an API key sent as a **Bearer token**:

```
Authorization: Bearer g_master_<token>
```

Keys are created from the Guayaba dashboard (Settings → API Keys).

#### Key Format

| Type       | Prefix      | Length                            |
| ---------- | ----------- | --------------------------------- |
| Master Key | `g_master_` | 57 chars (9-char prefix + 48 hex) |
| Agent Key  | `g_agent_`  | 56 chars (8-char prefix + 48 hex) |

Keys are shown **only once** at creation time. The server stores a SHA-256 hash — lost keys cannot be recovered, only regenerated.

#### Subscription Requirement

All endpoints require the key owner to have an **active subscription** (status: `active` or `trialing`). If the subscription is canceled, past due, or absent, every request returns `403`:

```json
{ "error": "Forbidden", "message": "An active subscription is required to use the API" }
```

This check runs **after** key validation and **before** any route-specific authorization.
