API keys
Create gateway keys for people and services, limit their permissions and source networks, attribute their traffic, and revoke them.
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. |
| Trace tags | Tags added to this key’s traces; see Observability |
| 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 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.