# API keys

> Create gateway keys for people and services, limit their permissions and source networks, attribute their traffic, and revoke them.

Product: AI Cost Optimizer Gateway (ACOG). Web version: https://tessarac.com/docs/acog/administer/api-keys. Last updated: 2026-10-16.

Gateway keys (`acog_…`) authenticate requests to the gateway and to the management API. Manage them on the **Developer** page. Anyone with gateway access can create keys for themselves; admins with the **Create and revoke API keys for anyone in the org** permission (`admin:keys`) can create keys for others and service keys.

## User keys and service keys

| | User key | Service key |
|---|---|---|
| Used by | A person, as themselves | An application, script or bot |
| Usage attributed to | The person | The key (and its application) |
| Limits and model rules | The person's | Set on the key itself |
| Who can create | Anyone, for themselves; admins, for anyone | Admins with `admin:keys` |
| Can belong to an application | No | Yes |

## Creating a key

On **Developer**, create a key and set:

| Setting | Notes |
|---|---|
| Name | Where the key is used, for example `ci-pipeline` |
| Type and owner | Admins only: user key for a chosen person, or service key |
| Permissions (scopes) | Default: gateway access only (`proxy`). A key can never have more permissions than you. |
| Application | Service keys only. See [Applications](https://tessarac.com/docs/acog/administer/applications.md). |
| Trace tags | Tags added to this key's traces; see [Observability](https://tessarac.com/docs/acog/administer/observability.md) |
| Cache lifetime | Override the provider prompt-cache lifetime for this key's requests |
| IP allowlist | IPv4 or IPv6 ranges (CIDR) this key may be used from. Empty means any source. |

**The key is shown once.** Copy it into your secret manager before closing the dialog: ACOG stores only a SHA-256 hash and cannot show it again.

A key with any admin permission is powerful: anyone holding it can change your organization. ACOG asks you to confirm, and recommends restricting it to specific IP ranges and binding it to a person.

## IP allowlist

A request from outside a key's allowlist is refused with `401` and a generic message, on both the gateway and the management API. On a self-hosted installation behind a load balancer, the operator must set `ACOG_TRUSTED_PROXY_CIDRS` so ACOG sees the real client address.

## Revoking a key

Deleting an active key **disables** it: requests with it fail with `401` within about five seconds. A disabled key can then be deleted permanently.

Keys are also revoked when their person is removed from the organization. Revocations are delivered as the `security.api_key_revoked` [webhook](https://tessarac.com/docs/acog/administer/webhooks.md) event.

## Rotating a key

Create a new key, deploy it, then disable the old one. To avoid an outage, keep both until every caller uses the new key.

## Keys for native AWS Bedrock access

boto3 and other AWS SDKs sign requests with an access key pair rather than sending a bearer token. For them, issue an ACOG Bedrock credential instead; see [AWS Bedrock](https://tessarac.com/docs/acog/providers/aws-bedrock.md#native-bedrock-access-with-boto3).