Developer · Pixel API

Pixel API authentication: API keys and scopes

Every Pixel API request carries a workspace API key in the Authorization header. Keys are created in Settings › API Keys, belong to one workspace, and can only do what the scopes ticked at creation allow.

Bearer token · Scopes fixed at creation · Shown once · Revoke anytime

Send the key

Authorization: Bearer wk_your_key_here

The word Bearer, a single space, then the key. Keys start with wk_.
Send the same header on every request, including GET /me.
Your workspace comes from the key. There is no workspace parameter to send, and nothing in a request can override it.

Create a key

Open Settings › API Keys and click Create key.
Under Name, describe the one integration that will hold the key — for example warehouse-etl or checkout-server.
Under What can this key do?, tick only what it needs (see the scopes table below). Read analytics is ticked by default.
Click Create, then Copy key. This is the only time the full key is shown: Admaxxer keeps a one-way fingerprint of it, never the key itself. Paste it straight into your secret manager.
Click Done. From then on the list shows only the key's prefix, its permissions, when it was last used and when it was created.

Prefer a guided version? The API keys guide walks through the same screen step by step.

Check a key

curl https://admaxxer.com/api/v1/me \
  -H "Authorization: Bearer $ADMAXXER_API_KEY"

{
  "apiKey": {
    "id": "…",
    "name": "checkout-server",
    "scopes": ["pixel:read", "pixel:write"]
  },
  "workspace": { "id": "…" }
}

The scopes list is the truth about what the key can do — check it first whenever a request is refused.

Scopes

Scope	Shown in Settings as	Lets the key
`pixel:read`	Read analytics	Call every `GET` endpoint in the Pixel API — websites, reports, live visitors, a visitor's goal history, goal property breakdowns — and read saved segments, including `POST /pixel/segments/{id}/apply`.
`pixel:write`	Write analytics	Send data from your server — `POST /pixel/goals`, `/pixel/payments`, `/pixel/events` and `/pixel/identify` — and create, rename and delete saved segments.
`ai:read`	Read AI Search	Read AI Search Visibility results. The Pixel API doesn't use it.

GET /me works with any valid key, whatever its scopes. A key without the scope an endpoint needs gets 403 insufficient_scope, and the response names the missing scope.

Treat write keys as powerful
A pixel:write key can add data to your reports, and it can also permanently delete goal conversions and payments recorded for your workspace. Give write access only to the system that sends data, and use read-only keys for reporting tools.

Rotate a key without downtime

Create a new key with the same permissions.
Deploy it to the integration and confirm requests succeed — GET /me is a quick check.
Watch the old key's Last used time in Settings stop changing.
Revoke the old key.

Permissions can't be edited on an existing key. To widen or narrow what a key can do, create a new key and revoke the old one.

Revoke a key

In Settings › API Keys, click the trash icon on the key's row and confirm Revoke key. The key stops working immediately — its next request returns 401 api_key_revoked — and it can't be restored. Revoked keys drop out of the list.

Keys created in Settings don't expire. They work until you revoke them.

Keep keys safe

Use one key per integration, named after it, so you can revoke one without touching the others.
Store keys in a secret manager or environment variables — never in source control, shared documents or screenshots.
Call the API only from servers you control. Browser code and app bundles can be read by anyone.
Revoke a key the moment it may have leaked. A replacement takes seconds to create.

Authentication errors

HTTP	Code	What happened	Fix
401	`not_authenticated`	No `Authorization` header on a Pixel API endpoint.	Add `Authorization: Bearer wk_…`.
401	`missing_authorization`	No `Authorization` header on `GET /me`.	Add the header.
401	`invalid_authorization_format`	The header isn't `Bearer`, one space, then the key.	Check for a missing `Bearer`, extra spaces or stray quotes.
401	`invalid_api_key`	The key isn't recognised — usually a typo or a truncated paste.	Copy the key again, or create a new one if you no longer have it.
401	`api_key_revoked`	The key was revoked.	Create a new key.
403	`insufficient_scope`	The key is valid but lacks the scope this endpoint needs. `details.required` names it; `details.available` lists what the key has.	Create a key with that scope ticked, switch over, then revoke the old one.

These errors are returned before the request reaches an endpoint, so the body is just the error object — no status and no meta:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the 'pixel:write' scope",
    "details": {
      "required": "pixel:write",
      "available": ["pixel:read"]
    }
  }
}

The full list of codes is on Errors.

Frequently asked questions

Q: Do API keys expire?

No. Keys created in Settings work until you revoke them.

Q: Can I change a key's scopes?

No — scopes are fixed when the key is created. Create a new key with the scopes you want, switch your integration to it, then revoke the old one.

Q: I lost a key. Can support show it to me?

No. Admaxxer stores only a one-way fingerprint of each key, so nobody can recover it. Revoke the lost key and create a new one.

Q: Does an API key work on the rest of the Admaxxer API?

No. API keys work on the Pixel API and GET /me, plus the AI Search Visibility endpoints for keys with ai:read. The dashboard's other endpoints use your signed-in session instead.

Q: Is a key tied to the person who created it?

No. A key belongs to the workspace it was created in, not to a person, so it keeps working if that person changes their password.

Q: How many keys can I create?

There's no limit. One key per integration is the pattern to follow, so retiring one never disturbs the others. All keys in a workspace share one rate limit.

Pixel API overview — Base URL, first request and response format.
Endpoints — Which scope each endpoint needs, with examples.
Errors — Every error code and how to fix it.
Rate limits — The per-workspace budget all keys share.
API keys guide — Step-by-step walkthrough of Settings › API Keys.
Developer reference — The wider developer documentation for Admaxxer.