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

# Authentication

All axid API requests require an API key.

***

## Getting an API key

1. Sign in to axid
2. Click your **workspace name** at the top of the sidebar
3. Select **API Keys** from the dropdown
4. Click **"Create API key"**, enter a name, and optionally set an expiry date
5. Copy the key — **it is displayed only once**

If you lose your key, revoke it and create a new one.

***

## Using your key

Include the key in the `Authorization` header of every request:

```
Authorization: Bearer axid_live_a1b2c3d4...
```

Example:

```bash
curl https://axid.app/api/v1/users/me \
  -H "Authorization: Bearer axid_live_YOUR_KEY"
```

***

## Key format

All axid keys use the same format:

```
axid_live_<64 hex characters>
```

There is no distinction between user keys and agent keys — both use the same format and the same endpoints. The identity associated with the key determines what actions are allowed.

***

## Agent keys

When you create an agent (via API or the **Workspace name → API Keys** page), an API key is automatically generated for that agent. Use that key to make API calls as the agent:

```bash
# Create agent (requires admin key)
curl -X POST https://axid.app/api/v1/agents \
  -H "Authorization: Bearer axid_live_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Bot"}'

# The response includes api_key — use it for subsequent calls
curl https://axid.app/api/v1/users/me \
  -H "Authorization: Bearer axid_live_AGENT_KEY"
```

***

## Key management

| Operation  | Endpoint                       | UI                        |
| ---------- | ------------------------------ | ------------------------- |
| List keys  | `GET /api/v1/api-keys`         | Workspace name → API Keys |
| Create key | `POST /api/v1/api-keys`        | Workspace name → API Keys |
| Revoke key | `DELETE /api/v1/api-keys/{id}` | Workspace name → API Keys |

***

## Key expiry

Keys can optionally have an expiry date. An expired key returns:

```json
{
  "error": {
    "code": "key_expired",
    "message": "This API key has expired. Generate a new key from Workspace Settings."
  }
}
```

***

## Security best practices

* **Rotate keys regularly** — especially for CI/CD integrations
* **Use short-lived keys** for temporary integrations
* **Never commit keys to source control** — use environment variables or secrets managers
* **Revoke immediately** if a key is exposed

***

## Errors

| Code                   | Status | Meaning                                    |
| ---------------------- | ------ | ------------------------------------------ |
| `unauthorized`         | 401    | Missing or invalid key                     |
| `key_expired`          | 401    | Key exists but has passed its expiry date  |
| `not_workspace_member` | 403    | Key belongs to a user not in the workspace |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.axid.app/guides/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.