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

# Authentication

> Create an API key in the Developer Portal and send it in a request header.

## What is this?

Every request is authenticated with an **API key** that belongs to a user. Requests act with that user's permissions, so a key can never do more than its owner could do in the app.

## What can I do here?

* Generate, regenerate, and revoke your API key in the Developer Portal
* Authenticate requests with the `X-API-Key` header or a bearer token
* Understand what each API family requires

## How to use it

### Create an API key

1. Open the profile menu and choose **Developer**.
2. In the **API Keys** panel, click **Generate API Key**.
3. Copy the key and store it somewhere safe.

<Warning>
  The raw key is shown **only once** and can't be revealed again — keys are stored hashed. If you lose it, click **Regenerate API Key** (this replaces the old key) or **Revoke** to remove access.
</Warning>

### Send the key

Send the key in one of these headers:

| Method             | Example                          |
| ------------------ | -------------------------------- |
| Header (preferred) | `X-API-Key: your_key`            |
| Bearer token       | `Authorization: Bearer your_key` |

```bash theme={null}
curl -X POST "https://YOUR_DOMAIN/api/workspace/v1/contacts/list" \
  -H "X-API-Key: YOUR_API_KEY"
```

<Note>
  API keys are **not** accepted in the query string or the request body, because those leak into logs, proxies, and referrer headers. Always use a header.
</Note>

### What each API needs

| API               | Requirement                                                                                                                            |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace API** | A valid API key. The request can only touch channels owned by the key's account — passing another workspace's `channelId` is rejected. |

## Troubleshooting / Technical Notes

* **`401` — Missing or invalid API key.** Send the key in the `X-API-Key` or `Authorization: Bearer` header. Keys in the query string or body are ignored.
* **Too many failed attempts.** Invalid keys are limited per IP address before authentication even runs — see [Rate limits](/api-reference/rate-limits).
* **I lost my key.** Use **Regenerate API Key** in the Developer Portal. The old key stops working immediately.
* **I can't open the Developer Portal.** You need the **API Access** permission (`settings:api`). Documentation stays browsable without it, but generating keys and trying requests do not.

## Related docs

* [Introduction](/api-reference/introduction)
* [Rate limits](/api-reference/rate-limits)
* [Errors](/api-reference/errors)
* [Team](/workspace/team)