Authentication & API keys

Every REST API and MCP request carries an API key. The key decides the workspace, the role and — for partner and advertiser keys — the account whose data is visible. Nothing in the request can widen that scope.

Sending the key#

curl https://app.trackcrown.com/api/v1/me -H "Authorization: Bearer atk_AbCd1234_0123456789abcdefghijABCDEFGHIJ0123456789"

X-Api-Key: atk_… is accepted instead of the Authorization header.

Keys look like atk_<8-character prefix>_<40-character secret> (letters and digits). The prefix is shown in the panel so you can tell keys apart. Only a SHA-256 hash of the full key is stored, so a lost key cannot be shown again: revoke it and create a new one.

Roles#

Admin keys act with workspace-admin permissions and analyst keys with analyst permissions; partner and advertiser keys hold no staff permissions at all.

Create a key#

Workspace staff#

1. Open Settings → API keys (Admin role).
2. Click Create API key.
3. Enter a Name — what uses it, e.g. BI export or CRM sync.
4. Choose Access: Analyst (read-only: reports, clicks, conversions, offers), Admin (read and write) or Advertiser (then pick the Advertiser; the key can never see other advertisers).
5. Click Create key and copy the key from the dialog. It is shown only once; the dialog also shows a ready curl command to try it.

The table lists Name, Key (prefix), Access, Status, IP allowlist, Last used, Created by and Created.

Partners#

Partners open API key from their account menu in the partner portal, click to create a key, give it a Name and copy it. The page has quick-start examples (Your stats by day, A tracking link with sub IDs, Your conversions). Up to 5 active keys per partner.

Advertisers#

Advertisers open API key from Profile (or the Integration page) in the advertiser portal. Up to 5 active keys per advertiser; at the limit the create button explains At most 5 active keys — revoke one first.

Revoke a key#

Revoke a key from the same page it was created on (advertisers: Revoke → Revoke key). Revoked keys answer 401 invalid_api_key immediately; the row stays in the list with its Revoked time.

IP allowlist#

Each key listed on Settings → API keys can be limited to addresses or ranges:

1. In Settings → API keys, click the IP allowlist cell of the key (it reads Any IP when empty).
2. In IP allowlist — <key name>, enter one address or CIDR range per line under Addresses / ranges:

203.0.113.10
198.51.100.0/24
2001:db8::/48

3. Save. Leave the box empty to allow any address.

Requests from other addresses get:

{ "error": { "code": "ip_not_allowed", "message": "This API key cannot be used from your IP address." } }

with HTTP 403. The allowlist is checked before the rate limit and also applies to the MCP server. Revoked keys cannot be edited.

Account status checks#

After the key is recognised, the request is refused when its account is not active:

Keeping keys safe#

• Use an Analyst key for reporting and BI; give Admin keys only to systems that must write.
• One key per system, so you can revoke one without breaking the others; the Last used column (updated at most once a minute) shows which keys are still in use.
• Store keys in a secret manager, never in front-end code — every request with the key acts on your workspace.
• Restrict server-to-server keys with an IP allowlist.

See also: Rate limits & errors · API reference.