# Authentication

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

```
Authorization: Bearer <your-api-key>
```

### Key Types

Guayaba uses a two-tier key system:

#### Master Key (`g_master_`)

* **One per user.** Creating a new one revokes the previous master key and all its agent keys.
* Full access to every endpoint and every agent you own.
* Required for: creating/updating/deleting agents, billing endpoints, and managing API keys.
* Format: `g_master_` + 48 hex characters (57 chars total).

#### Agent Key (`g_agent_`)

* **One per agent.** Tied to a single agent by ID.
* Limited access controlled by **scopes** you choose at creation time.
* Cannot access other agents — returns `403` if attempted.
* Format: `g_agent_` + 48 hex characters (56 chars total).

### Creating Keys

Keys are managed from the Guayaba dashboard:

* **Master Key**: Settings → API Keys → Create Master Key
* **Agent Key**: Agent Detail → API Keys → Create Agent Key

> **You must have an active master key before creating agent keys.** If your master key is revoked, you need to create a new one first.

> The full key is shown **only once** at creation. Store it securely — lost keys cannot be recovered, only regenerated.

### Scopes

Scopes control what an agent key can do. Master keys bypass all scope checks.

| Scope          | Description                                              | Included by default |
| -------------- | -------------------------------------------------------- | ------------------- |
| `agent:read`   | View agent details and configuration                     | Always              |
| `agent:manage` | Start, stop, pause, reload. Manage sessions and archives | No                  |
| `channels`     | Manage Telegram pairing (list, approve, revoke, reject)  | No                  |
| `files`        | Upload files to the agent                                | No                  |
| `chat`         | Send messages to the agent via API                       | No                  |

`agent:read` is always included automatically in every agent key.

### Subscription Requirement

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

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

### Key Revocation

* **Revoking a master key cascades** — all agent keys under that user are also revoked.
* Regenerating a key revokes the old one and creates a new one.
* Revoked keys return `401 Unauthorized` immediately.

### Key Expiration

Keys can optionally be set to expire at a specific date. By default, keys do not expire. Expired keys behave the same as revoked keys (`401`).

### Example

```
# Using a master key
curl https://api.guayaba.run/api/v1/agents \
  -H "Authorization: Bearer g_master_a1b2c3d4e5f6..."

# Using an agent key (with agent:read scope)
curl https://api.guayaba.run/api/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer g_agent_f6e5d4c3b2a1..."
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.guayaba.run/documentation/api-guide/markdown.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.