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. Each key has specific scopes that control which endpoints it can access, along with IP allowlisting, rotation, and audit logging.

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.

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 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:

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 for available endpoints.

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 and Clerk JWT respectively.

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

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

403 Forbidden

• The key is valid but does not have the required scope. Edit the key to add the missing scope.

429 Too Many Requests

• Rate limit exceeded. Wait and retry. The limit is 300 requests per minute per IP.

Related Documentation

• Public API v1 Reference
• Security Overview
• Widget Authentication