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

# API Key Authentication

> Authenticate server-to-server requests with scoped API v1 keys

AGO provides scoped API keys to authenticate server-to-server requests to the [Public API v1](/api/public-api-v1). Each key has specific scopes that control which endpoints it can access, along with IP allowlisting, rotation, and audit logging.

<Warning>
  **Legacy API keys are deprecated.** If you are using a legacy API key (configured in Settings > Integrations > API Configuration), migrate to API v1 scoped keys. Legacy key generation is no longer available. Existing legacy keys continue to work but will be removed in a future update.
</Warning>

## Create an API Key

1. Go to **Settings > Integrations > API Keys**
2. Click **Create API Key**
3. Enter a name for the key
4. Select the scopes your integration needs (see [Available Scopes](#scopes) below)
5. Optionally add IP allowlist restrictions (CIDR notation)
6. Click **Create**
7. Copy the key immediately — it is shown only once

## Scopes

Each key is assigned scopes that control endpoint access:

| Scope                       | Access                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------- |
| `knowledge:read`            | Read documents, sources, translations, and versions                                   |
| `knowledge:write`           | Create, update, delete, and bulk-manage documents and sources                         |
| `conversations:read`        | Read conversation threads, messages, and feedback                                     |
| `conversations:write`       | Update thread evaluation, admin comment, admin tags, and admin status                 |
| `tickets:read`              | Read tickets, statuses, statistics, and messages                                      |
| `analytics:read`            | Read dashboard analytics data                                                         |
| `agents_config:read`        | Read agents, tools, prompt templates, and UI resource templates                       |
| `agents_config:write`       | Create, update, and delete agents, tools, prompt templates, and UI resource templates |
| `custom_data_sources:read`  | Search and read rows from smart tables                                                |
| `custom_data_sources:write` | Create, update, delete smart tables and push or delete rows                           |
| `*`                         | Full access: grants every API v1 endpoint, present and future                         |

A key with a `write` scope automatically has the corresponding `read` scope. For example, `knowledge:write` includes `knowledge:read`. The `*` scope satisfies any scope check and overrides every other selection.

## Make API Requests

Include the API key in the `X-API-Key` header:

```bash theme={null}
curl https://your-tenant-id.api.useago.com/api/v1/documents \
  -H "X-API-Key: ago_v1_sk_your_key_here"
```

All API v1 endpoints are under `/api/v1/`. See the [Public API v1 reference](/api/public-api-v1) for available endpoints.

<Note>
  Scoped API keys only work with `/api/v1/` endpoints. They cannot be used to authenticate SDK/widget requests (`/api/sdk/v1/`) or internal API requests — those use [widget authentication](/security/security) and Clerk JWT respectively.
</Note>

## Security Features

**IP allowlisting** — Restrict a key to specific IP addresses or CIDR ranges. Requests from other IPs are rejected.

**Automatic lockout** — After 10 consecutive authentication failures, a key is locked. Unlock it from the API Keys management page.

**Audit logging** — Every API request is logged with the key used, endpoint called, response status, and client IP.

**Key rotation** — Rotate a key to generate a new secret while keeping the same scopes and settings. An optional grace period keeps the old key active during the transition.

## Rotate a Key

1. Go to **Settings > Integrations > API Keys**
2. Click on the key you want to rotate
3. Click **Rotate Key**
4. Set a grace period if needed (the old key stays active for that duration)
5. Copy the new key and update your integration
6. After the grace period expires, the old key stops working

## Revoke a Key

1. Go to **Settings > Integrations > API Keys**
2. Click on the key you want to revoke
3. Click **Revoke**

Revoked keys stop working immediately.

## Migrate from Legacy API Keys

If you have a legacy API key (configured in Settings > Integrations > API Configuration):

1. Create a new API v1 key with the scopes your integration needs
2. Update your integration to use the new key and the `/api/v1/` endpoints
3. Delete the legacy key from Settings > Integrations > API Configuration

Legacy keys provided access to the internal API (`/api/`). API v1 keys are scoped to `/api/v1/` endpoints, so you only grant the access your integration actually needs.

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    * Check that the `X-API-Key` header is present and correct
    * Verify the key has not been revoked or expired
    * Confirm the key has the required scope for the endpoint
  </Accordion>

  <Accordion title="403 Forbidden">
    * The key is valid but does not have the required scope. Edit the key to add the missing scope.
  </Accordion>

  <Accordion title="429 Too Many Requests">
    * Rate limit exceeded. Wait and retry. The limit is 300 requests per minute per IP.
  </Accordion>
</AccordionGroup>

## Related Documentation

* [Public API v1 Reference](/api/public-api-v1)
* [Security Overview](/security/security)
* [Widget Authentication](/security/widget-authentication)