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

# Authentication

> Generate, rotate, revoke, and use your Xobito API token.

Every request to the Xobito API must include a bearer token. **Each workspace has a single API token**, generated and managed from the dashboard. There is no concept of multiple tokens, per-token names, ability subsets, monthly quotas, or expiry dates — your one token grants all configured abilities for the workspace.

## Token format

A Xobito API token is a **64-character hexadecimal string** with no prefix:

```
<your_token>
```

<Warning>
  Treat the token like a password. Anyone with it can call every API endpoint on your workspace. Store it in a secrets manager — never commit it to source control or expose it to client-side code.
</Warning>

## Generating a token

<Steps>
  <Step title="Open API Management">
    In your dashboard, go to **Settings → API Management**.
  </Step>

  <Step title="Enable API access">
    Flip the **Enable API Access** toggle on. The first time you do this, a token is generated automatically.
  </Step>

  <Step title="Copy the token">
    The token is displayed in the **API Token** field. Copy it into your password manager or secrets vault immediately.
  </Step>

  <Step title="Save">
    Click **Save** to persist the change.
  </Step>
</Steps>

## Using a token

Send the token in the `Authorization` header on every request:

```bash theme={null}
curl https://dash.xobito.com/api/v1/acme/contacts \
  -H "Authorization: Bearer <your_token>" \
  -H "Accept: application/json"
```

## Abilities

A workspace token automatically grants **every API ability** Xobito ships. There is no UI to issue narrower tokens; abilities are managed server-side in module configuration. The full ability list (used for documentation and internal authorisation checks):

| Ability                                                          | Grants                                                                            |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `contacts.create`                                                | Create contacts                                                                   |
| `contacts.read`                                                  | List / read contacts                                                              |
| `contacts.update`                                                | Update contacts                                                                   |
| `contacts.delete`                                                | Delete contacts                                                                   |
| `statuses.create`                                                | Create contact statuses                                                           |
| `statuses.read`                                                  | List / read statuses                                                              |
| `statuses.update`                                                | Update statuses                                                                   |
| `statuses.delete`                                                | Delete statuses                                                                   |
| `sources.create`                                                 | Create contact sources                                                            |
| `sources.read`                                                   | List / read sources                                                               |
| `sources.update`                                                 | Update sources                                                                    |
| `sources.delete`                                                 | Delete sources                                                                    |
| `groups.create`                                                  | Create groups                                                                     |
| `groups.read`                                                    | List / read groups                                                                |
| `groups.update`                                                  | Update groups                                                                     |
| `groups.delete`                                                  | Delete groups                                                                     |
| `templates.read`                                                 | List / read WhatsApp templates                                                    |
| `templatebots.read` / `templatebots.delete`                      | Read / delete template-bot definitions                                            |
| `messagebots.create` / `messagebots.read` / `messagebots.delete` | Manage message-bot definitions                                                    |
| `messages.send`                                                  | Send text, template, media messages; validate phone numbers; check message status |

<Note>
  Because every token holds every ability, there is no "missing ability" scenario in normal use. The `403 Token does not have the required ability` error only fires if abilities are removed via direct configuration on the server.
</Note>

## Rotating a token

To invalidate the current token and issue a new one:

<Steps>
  <Step title="Open Settings → API Management">
    Same page used to generate the original token.
  </Step>

  <Step title="Click Generate New Token">
    The displayed token is replaced immediately. Save the new value to your secrets manager.
  </Step>

  <Step title="Save">
    Click **Save**. The previous token stops working as soon as the change is persisted.
  </Step>
</Steps>

<Warning>
  Rotation is a hard cutover — there is no grace period. Update every integration with the new token at the same time you save, or your integrations will start receiving `401 Invalid API token`.
</Warning>

## Revoking access

To stop all API access without issuing a new token, flip the **Enable API Access** toggle off in **Settings → API Management** and save. Every subsequent request returns:

```json theme={null}
{
  "status": "error",
  "message": "API access is disabled"
}
```

Toggle the switch back on later to re-enable the existing token.

## Rate limits

Default: **60 requests per minute per token** (configurable per workspace). When the limit is exceeded, the API responds with `429 Too Many Requests` and a `retry_after` field (in seconds). See [Rate Limits](/developers/rate-limits) for the full details and headers.

## Errors

### Missing token

HTTP `401`:

```json theme={null}
{
  "status": "error",
  "message": "API token is required"
}
```

### Invalid token

HTTP `401`:

```json theme={null}
{
  "status": "error",
  "message": "Invalid API token"
}
```

### API disabled

HTTP `403`:

```json theme={null}
{
  "status": "error",
  "message": "API access is disabled"
}
```

### Missing ability

HTTP `403` (rare — only when an ability has been removed server-side):

```json theme={null}
{
  "status": "error",
  "message": "Token does not have the required ability: contacts.create"
}
```

## Security checklist

<Check>Store the token in a secrets manager — never commit it to source control.</Check>
<Check>Rotate the token on a regular cadence or whenever a team member with access leaves.</Check>
<Check>Disable API access entirely if you suspect leakage, then rotate.</Check>
<Check>Always use HTTPS — the token travels in the `Authorization` header on every request.</Check>