Get started

Authentication and API keys

How the data API authenticates requests, what an API key is, and the limits you can set on it.

The data API (https://api.aggre.org) accepts API keys only. The accounts service behind the console (https://accounts.aggre.org) accepts session cookies only and never an API key. The two never mix.

Sending the key#

http

GET /v1/whoami HTTP/1.1
Host: api.aggre.org
Authorization: Bearer aggre_sk_...

X-API-Key: aggre_sk_... is accepted instead of the Authorization header. Every /v1/* route needs a key; GET /healthz and GET /readyz do not.

What a key is#

The format is aggre_sk_ followed by 43 characters of base64url (32 random bytes).
The secret is shown once, when you create the key, and is never returned again. Aggre stores a SHA-256 hash and the first 8 characters after aggre_sk_ as a non-secret display prefix; listings show only that prefix.
A key belongs to an account: your personal account or an organization. Members with the right role manage the organization's keys (roles).
Never put a key in client-side code, a repository, a log or a URL. Calls to the data API belong on a server or in an agent's tool configuration.

Limits you can set#

Each key has:

Setting	Meaning
Quota (`usage_limit`) and period (`usage_period`: `day`, `month` or `total`)	How many requests the key may make per period. Once spent, requests answer `429 usage_limit_exceeded`.
IP allowlist (`ip_allowlist`)	A list of CIDR ranges the key may be used from. Empty means open. Outside the list: `403 ip_not_allowed`.
Expiry (`expires_at`)	Optional date after which the key stops working.
Rate policy (`rate_policy`)	`default`. `exempt` exists for platform staff only.

Self-service keys have a monthly allowance (the default is shown in the console when you create a key; a day quota counts as up to 31 times its limit against that allowance), and an account can hold at most 20 active keys. Unlimited keys, exempt rate policy and quotas above the default are set by platform staff.

Revoking and rotating#

Revoke a key in the console. Revocation reaches the API within about 30 seconds (the gateway caches keys for that long). To rotate: create the new key, deploy it, then revoke the old one.

Usage counting#

Each request made with a key is recorded as a usage event: time, method, route template (never the raw URL or query string), dataset id, HTTP status and request id. Your IP address and query text are not stored. The count in GET /v1/whoami and in the console is the key's counter for its current period; it can lag a few seconds because the gateway writes counters in batches. GET /v1/whoami itself counts as a normal request. See Usage and audit log.

Errors you will see#

Status	`error.code`	Cause
401	`unauthorized`	Missing, malformed, unknown or revoked key.
403	`ip_not_allowed`	The key has an allowlist and the request came from elsewhere.
403	`forbidden`	The account is disabled.
429	`rate_limited`	Per-source-IP limit, checked before the key. Retry after `Retry-After`.
429	`usage_limit_exceeded`	The key's quota is spent. Retrying will not help.

Details: Errors and Rate limits and quotas.

Source: content/authentication.md