Authentication

All endpoints require a Bearer token in the Authorization header.


Authorization: Bearer atk_live_<prefix>_<secret>

New tokens are account-scoped by default. A single token can fire events for any site in the account by resolving the Telegram lead context. Older site-scoped tokens continue to work and remain limited to their original site.

Token format

A full token looks like:


atk_live_a1b2c3d4_xyzabc123def456ghi789jklmno000
└──┬──┘ └───┬───┘ └──────────────┬──────────────┘
   │       │                       │
   │       │                       └─ 32-char secret (only shown once)
   │       └─ 8-char public prefix (visible in your dashboard)
   └─ stable namespace

Only the prefix and a SHA-256 hash of the secret are stored on our side. The full token is shown exactly once — when you create it.

Creating a key

Open the API tab

Dashboard → Site → Settings → API. New keys created here are account-wide; legacy site keys remain visible and revocable.

Click “Create API key”

Give it a memorable name (e.g. Production backend, Cloudflare Worker).

Copy the token

Click “Copy to clipboard” in the reveal modal. This is the only time the full token will appear.

If you lose a token, revoke it and create a new one. We cannot recover lost tokens.

Rotating a key

To rotate a key without downtime:

Create a new key.
Update your backend to use the new key.
Deploy and verify with a test request.
Revoke the old key in the dashboard.

The old key returns 401 immediately on revoke — no grace period.

Limits

Each account can have up to 5 active account-scoped keys.
Each site can still have up to 5 active legacy site-scoped keys.
Tokens never expire on their own — they remain valid until you revoke them.

Best practices

Store tokens in environment variables, not in code.
Use a different token per environment (production, staging, dev).
Rotate tokens at least once a year.
Set up an alert if lastUsedAt advances for a key you thought was unused — that’s a sign of a leak.

Feature flag

The public API is gated by the env var ADTARGET_PUBLIC_API_ENABLED on our end. If you receive 503 API_DISABLED, the API is paused on our deployment — contact support.