Apps and keys
List apps
Section titled “List apps”Scope read:creatives.
curl -s https://api.ad80.dev/v1/apps -H "Authorization: Bearer $AD80_API_KEY"{ "apps": [ { "appId": "com.example.news", "name": "Example News", "createdAt": "2026-10-20T08:00:00Z", "lastUploadAt": "2026-10-28T09:12:44Z", "sdkVersion": "0.2.0", "policyVersion": 3, "creativeCount": 412, "playground": false } ]}playground: true marks the organization’s Policy Playground app; leave it out of SDK lists. lastUploadAt is the
last accepted upload from the SDK (null before the first). sdkVersion and policyVersion can be null.
Get an app
Section titled “Get an app”Scope read:creatives. One app in the same shape. Poll it to wait for the first upload (lastUploadAt). 404 when
the app does not exist in your organization.
Create an app
Section titled “Create an app”Scope manage:keys.
curl -s -X POST https://api.ad80.dev/v1/apps \ -H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \ -d '{"appId": "com.example.news", "name": "Example News"}'| Field | Rules |
|---|---|
appId | Required. The app’s id: the Android application id, or the iOS bundle identifier that the SDK sends. At least two segments separated by dots, each starting with a letter, then letters, digits or _. Up to 150 characters. A hyphen is not accepted, so a bundle identifier that contains one (which Apple allows) is rejected with 400 today. |
name | Optional display name, up to 100 characters. |
201 with the app. 409 when the app id already exists in your organization.
List keys
Section titled “List keys”Scope manage:keys. Lists upload keys (ingest) and API keys (client). Secrets are never returned, only a
non-secret prefix (the first 12 characters).
{ "keys": [ { "id": "ik_7", "type": "ingest", "prefix": "ad80_ik_Ab3x", "label": "Release build", "appId": "com.example.news", "createdBy": "user:31", "createdAt": "2026-10-20T08:01:00Z", "lastUsedAt": "2026-10-28T09:12:44Z", "expiresAt": null, "revokedAt": null }, { "id": "ck_3", "type": "client", "prefix": "ad80_ck_Q9zL", "label": "Nightly export", "scopes": ["read:creatives", "read:verdicts"], "createdBy": "user:31", "createdAt": "2026-10-21T10:00:00Z", "lastUsedAt": null, "expiresAt": "2027-10-21T10:00:00Z", "revokedAt": null, "rotatedFrom": "ck_1" } ]}lastUsedAt is updated at most once a minute.
Create or rotate a key
Section titled “Create or rotate a key”Scope manage:keys.
| Field | Meaning |
|---|---|
type | client (default) or ingest. |
label | Optional, up to 100 characters. |
scopes | Client keys: at least one scope. A key can only grant scopes it has itself (403 otherwise). |
appId | Ingest keys: the app the key uploads for (required unless rotating). |
expiresInDays | Optional, 0 to 3650. 0 or absent: no expiry. |
rotates | Optional id of an active key to replace, for example ik_7 or ck_3. The new key keeps the old key’s scopes or app. |
graceHours | With rotates: the old key expires this many hours later (0 to 8760). 0 or absent: the old key stays valid until you revoke it. |
Create an upload key for an app:
curl -s -X POST https://api.ad80.dev/v1/keys \ -H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \ -d '{"type": "ingest", "appId": "com.example.news", "label": "Release build"}'Create a read-only API key that expires in a year:
curl -s -X POST https://api.ad80.dev/v1/keys \ -H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \ -d '{"type": "client", "label": "BI export", "scopes": ["read:creatives", "read:verdicts"], "expiresInDays": 365}'Rotate an upload key, keeping the old one valid for 30 days while the app update rolls out:
curl -s -X POST https://api.ad80.dev/v1/keys \ -H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \ -d '{"rotates": "ik_7", "graceHours": 720}'201 response. key is the secret and is shown only here:
{ "id": "ik_8", "key": "ad80_ik_THE_NEW_SECRET", "prefix": "ad80_ik_Zx81", "expiresAt": null, "note": "the key is shown once; store it now"}Client keys also return scopes. Creating an upload key on a plan without SDK integration answers 403 with
entitlement: sdk_ingest.
Revoke a key
Section titled “Revoke a key”Scope manage:keys. id is ck_<n> or ik_<n>. The key stops working at once.
curl -s -X POST https://api.ad80.dev/v1/keys/ik_7/revoke -H "Authorization: Bearer $AD80_API_KEY"{ "id": "ik_7", "revoked": true }In rare cases the response adds warning: the revocation then takes effect within 30 seconds.