Authentication and keys
One header, keys your organization manages, and permissions you can narrow.
Updated · API v1
The Authorization header
Authorization: Bearer adspy_sk_…Send the key on every request. A missing, unknown, expired or revoked key, or a request from an address the key does not allow, answers 401 unauthorized with the same message: the answer never says which.
The API is server to server. It sends no CORS headers, so a browser page cannot call it, and it must not: a key in a page is a published key.
Organization keys
Organization keys start with adspy_sk_, followed by 49 letters and digits whose last six are a checksum. The fixed prefix lets secret scanners recognize a leaked key; the checksum lets Adspy refuse a mistyped one at once.
Owners and admins create, edit, rotate and revoke them in Settings, then API, and see each key's use and the organization's request log there. An organization holds up to 100 active keys.
Personal MCP keys (adspy_key_) of an Enterprise organization also work, with their own permissions. Use organization keys for servers: they do not depend on a member's account.
Permissions
| Permission | Allows |
|---|---|
| read | Every GET on brands, creatives, analyses, similar creatives, advertisers, social accounts and posts, posts run as ads, collections and usage. Always granted. |
| actions | Work that costs or changes something: new collections (POST /v1/fetches, POST /v1/social/fetches) and their jobs, X-Ray, social reports, Full Analysis, comparisons, saving creatives and notes. |
| export | Creating exports and reading their jobs and files. |
A request outside the key's permissions answers 403 insufficient_scope. Changes to permissions apply to the next request.
Lifetime, rotation and revocation
- A key lives 30, 90 (the default) or 365 days, then stops working. Its expiry date shows in Settings, then API.
- Rotating a key issues a new secret with the same permissions, addresses and history. The previous secret keeps working for 24 hours, so you can deploy the new one without downtime.
- Revoking a key stops it at once, every secret included.
- If a key leaks, revoke it first, then create a new one. Requests already answered stay in the request log with the key's name, never its secret.
IP allowlist
A key can be limited to up to 50 IPv4 or IPv6 addresses or CIDR ranges, such as 203.0.113.0/24 or 2001:db8::/48. A request from another address answers 401. An empty list allows every address.
How Adspy stores keys
Adspy keeps only a keyed hash of each key (HMAC-SHA-256 with a server secret), never the key itself, and compares it in constant time. Adspy cannot show a key again: a lost key is rotated, not recovered.
The request log records each request's key (its id and name), route, status, address, user agent and time, and keeps them 90 days. It never holds the key itself, a query string or a request body.