API keys

Every request to the API must include a Bearer token in the Authorization header:

Authorization: Bearer $AGGREGATOR_API_KEY

You obtain API keys from the operator cabinet at app.aggregator.gg/api-keys.

Current and legacy keys

New operator API keys start with agg_, followed by 43 Base62 characters (letters and digits). New keys have a stored live environment; the cabinet does not issue new test keys. A key supplies authentication, not a free test budget or permission to move money. Confirm access, credits and test limits with the operator. Environments separates demos from controlled wallet tests.

Legacy keys. Existing sk_live_ keys still authenticate for live traffic, subject to the same key permissions, revocation, and deprecation checks. Core also retains authentication for existing sk_test_ keys in their original test environment; the cabinet no longer issues them. For a new integration, use demo sessions for game presentation and a separately approved, budgeted wallet test for settlement. Do not change a key’s prefix: use the complete value the cabinet issued.

Creating a key

1. Register as an operator at app.aggregator.gg/register.
2. Navigate to API Keys in your cabinet and create your agg_ key.
3. Copy the key immediately. It is shown once, at creation time.

KYB verification is not a technical precondition for minting a key. You can create a working agg_ key and integrate against the API while your KYB file is still open. KYB stays a commercial and compliance requirement for operating on the platform, so start it early and run it alongside the integration; it is simply not the thing that blocks your first API call.

Your callback secret is a separate credential used to verify callback signatures, never sent as a Bearer token. Operator accounts configure it on the API page under Callbacks (the integration setup wizard writes the same setting and can generate a value), and the cabinet never displays it after saving, so store it in your secret manager at that moment. See Request signatures.

A key is scoped by its issuing identity, organization context and stored permissions. Platform keys additionally select brands on supported endpoints; create and configure the brand before testing the catalog. See Platform accounts. Platform callback setup can require support because the operator callback editor is not exposed for that account type.

Step check: a GET /v1/games request with your new key returns 200:

curl -s "https://api.aggregator.gg/v1/games?per_page=1" <<EOF \
  --header @-
Authorization: Bearer ${AGGREGATOR_API_KEY:?Set the issued key in the protected environment}
EOF

An unrecognized key returns 401 with the flat body {"error": "invalid_token", "message": "API key authentication failed"}; E5002 api_key_invalid is the error reference name for this condition, and it does not appear in the auth response body today. Match on the status code. See Errors.

Storing keys safely

• Never commit keys to git. Use environment variables or a secret manager such as 1Password, Vault, or AWS Secrets Manager.
• Never expose API keys in browser-side code. This API is server-to-server only.
• Use a dedicated key for CI and integration tests rather than your production key. The cabinet lets you name keys (for example prod-main, ci-runner) and revoke them independently.
• Treat welcome-pack traffic the same as paying traffic. The platform does not distinguish them in the API, and neither should your code.

Key lifetime

Keys do not expire. A key authenticates until you revoke it. There is no platform-enforced lifetime, no renewal step, and nothing to schedule around.

That covers keys you already hold as well. The 90-day expiry was withdrawn on 26 August 2026: authentication no longer reads the expiry date at all, so a key created before that date keeps working past the date stamped on it, and keys created since carry no date. Nothing needs replacing on a deadline.

Rotate on your own schedule, by overlap, as described in the next section. One deadline does exist, and only if you use it: if a key is marked deprecated, it stops authenticating 24 hours after that mark.

Replacing a key

There is no one-click rotation control in the cabinet today. Replace a key by running two keys side by side for as long as your deploy needs, then retiring the old one:

1. In the cabinet, create a second agg_ key under a new name, for example prod-2026-08. Keep a free issuance slot for the replacement: the limit is 10 non-revoked keys per issuing user. If the limit is reached, retire an unused key first; do not revoke the working key merely to begin a routine rollout.
2. Deploy the new key. Both keys authenticate, so the overlap lasts exactly as long as your rollout does rather than a fixed window.
3. Confirm the old key has gone quiet. The API Keys page shows a Last used timestamp per key.
4. Revoke the old key from the cabinet. Revocation takes effect immediately.

Keys are independently revocable. On suspected compromise, assess any other credentials exposed through the same system before declaring the incident contained.

Step check: with both keys live, the same GET /v1/games request returns 200 under either one. After you revoke the old key, it returns 401 and the new key still returns 200.

Revocation

On suspected compromise, the human revokes the exposed key immediately through the cabinet; do not delay containment to finish a routine overlap. Create and deploy a protected replacement, then verify the revoked key returns 401 and the replacement works. A temporary integration outage may be necessary to stop unauthorized access.