Required headers
The API key is scoped to a single Adclear organisation and workspace. Rate limits apply per key (see Errors & rate limits).
Key expiry
Keys generated in Settings stop working at the expiry you chose when you generated them: 30 days by default, or 90 days, 1 year, or never. Keys Adclear provided during onboarding don’t expire. Once a key expires, the File API and the Adclear API reject every request made with it with401 and a message ending in Code: KEY_EXPIRED. You can’t extend an expiry. Generate a replacement before the date, switch your integration to it, then revoke the old key.
Keys tied to their creator
A key generated in Settings acts as the person who generated it. On every request, the File API and the Adclear API check that this person is still a member of your organisation in a role that can hold a key. If they have left the organisation, or now hold an external role (external uploader or reviewer), both APIs reject every request made with the key with403. The Adclear API returns the message API key is not configured for public API access. The File API returns API key is not configured for file uploads. Keys Adclear provided during onboarding are not affected.
Generate integration keys from a long-lived account. Before the person who generated a key leaves or changes role, generate a replacement from another account, switch your integration to it, then revoke the old key.
Acting on behalf of Adclear users
By default, actions performed through the API are attributed to the key’s service account, with yourX-External-User-ID value recorded alongside for audit purposes. The ID is stored as supplied. Adclear does not verify it.
Keys can instead be issued with act-on-behalf enabled, for integrations whose users also have Adclear accounts. On these keys, X-External-User-Email is resolved to the Adclear user with that email, and the action is performed and audited as that person, with their own role and permissions. Two rules apply:
- The email header is mandatory on every write (
POST,PUT,PATCH,DELETE). Writes without it are rejected with 400. - An email that does not match an active member of your organisation is rejected with 403. The action is never silently attributed to the service account.
author.email when importing or updating comments: only act-on-behalf keys can attribute a comment or action to another member. On ordinary keys, an imported comment from another member’s email is recorded as an external author. Ask your Adclear contact if you are unsure which kind of key you hold.
Permissions
The Adclear API applies the same permission checks as the Adclear app. It checks the acting user: the user named inX-External-User-Email on act-on-behalf keys, otherwise the key’s own user. For a key generated in Settings, that is the person who generated it.
- The acting user must be a current member of your organisation.
- If your organisation has more than one workspace, the acting user needs access to the key’s workspace. Admins manage this in the Workspace access column of Settings > Organisation > Users.
- Creating a version (
POST /v1/promotions/{promotionId}/versions) and submitting a version for review (POST .../submit) need a role that can submit promotions. External reviewers can’t. - Recording a decision and setting or removing a reviewer follow the same review permissions and self-approval rules as the app.
403 FORBIDDEN, and the error message says which check failed (see Errors & rate limits). A promotion or version ID from another organisation or workspace returns 404 NOT_FOUND, the same as an ID that doesn’t exist.
Environments
API keys are environment-specific. A staging key won’t authenticate against production, and vice versa.
Interactive API reference
Explore and try endpoints in Swagger UI:- Adclear API: https://public-api.adclear.ai/v1/docs
- File API: https://files.adclear.ai/v1/docs
GET https://public-api.adclear.ai/v1/openapi.jsonGET https://files.adclear.ai/v1/openapi.json