Skip to main content
Every TrackPlay API call is authenticated with a scoped token you mint in the dashboard. A token carries a fixed set of scopes. A token with no matching scope is rejected. It cannot be talked into doing more than it was issued for.

​
Mint a token

1

Open your workspace settings

In the dashboard sidebar, click Settings, then the API tokens tab.
2

Create the token

Click New token. Give it a name you will recognise later. It shows up in the token list and in your audit log, so Zapier production beats token 2.
3

Grant only the scopes it needs

Tick the scopes this integration actually uses. A backend that only posts events needs events:write and nothing else.
4

Set an expiry, or do not

Leave the expiry blank for a token that never expires. Anything from 1 to 3650 days is accepted.
5

Copy it now

The token is shown once. TrackPlay stores only a SHA-256 hash of it, so nobody (including us) can show it to you again. Lost it? Revoke it and mint another.

​
Scopes

Six scopes are enforced on live endpoints. Each one below names exactly what it unlocks.
​
write-only
Send events to the Custom Events API. Write-only: it cannot read anything back, which makes it the right token to hand to a third-party backend. This is the only scope the events host checks.
​
write-only
Send sales to the Conversions API.
​
read-only
Read the Analytics API: summary, retention, raw events and conversions, plus queueing and polling exports.
​
read-only
List and read videos, their settings, their embed code and their player config. It also covers reading playlists and workspace metadata, which has no scope of its own.
​
write-only
Create, update, duplicate and delete videos. Save a settings draft, deploy it, and restore a past version. Upload media. Replace captions, chapters, AI segments and CTA cards. Create and edit playlists.
​
write-only
Manage webhook subscriptions, send test deliveries, and drive the Zapier REST hooks.

​
Reserved scopes

Three more scopes can be ticked when you mint a token: conversions:read, integrations:read, and workspace:read.
No endpoint checks any of them today. A token minted with only a reserved scope is accepted as a valid token and then rejected by every endpoint you point it at, because none of them is the scope that endpoint requires.They are reserved for read endpoints that do not exist yet. Do not build against them. To read workspace metadata today, use videos:read.

​
Send the token

Either header works. Pick one.
The token decides the workspace. You never send a workspace ID, and you cannot write into a workspace your token does not belong to.

​
Base URLs

Events run on their own host because they run at a different volume. Same token, same scopes.

​
When auth fails

No token reached us. Check the header name and that your HTTP client is not stripping it on redirect.
The token is wrong, expired, or revoked. Tokens are matched on an exact hash: a stray space or newline will land here.
The token is valid but was not granted the scope this endpoint needs. The response names the scope in required. Mint a new token with it; you cannot add a scope to an existing token.
Token verification is temporarily unavailable. This is not a rejection of your token. We fail closed rather than let an outage authenticate anyone, so retry shortly rather than re-issuing credentials.This code is returned by the events host (https://e.trackplay.io). The app API on https://app.trackplay.io does not use it.

​
Rotating and revoking

Revoke a token from the same Settings → API tokens tab. Revocation is immediate at the source, and takes effect on the events host within 5 minutes as its auth cache expires.
Revoking breaks every integration using that token, straight away. To rotate without downtime: mint the new token, deploy it, confirm traffic has moved, then revoke the old one.

​
The legacy workspace key

Older workspaces have a single tp_ API key with blanket access to everything, including analytics reads. It still works, and it is deprecated.
The Custom Events API rejects the legacy key outright. A key that can read all your analytics has no business sitting in a third-party backend to post events. Mint a scoped events:write token instead.
Legacy-key responses carry a Deprecation header. Move to scoped tokens when you touch the integration next.