Authentication

Create a key

1. Sign in and open Profile → API keys.
2. Give the key a name you will recognise later, such as “Reporting script”.
3. Choose its access (read only, or read and write) and when it expires: 30 days, 90 days, 1 year, or never.
4. Confirm your password and copy the key. It starts with tk_live_ and is shown once; Tracker only stores a hash of it.

We email you whenever a key is created on your account, so a key you did not create never goes unnoticed.

Send the key

Put the key in the Authorization header of every request, after Bearer. Keys never create browser sessions and do not need CSRF tokens. To check a key, call GET /me:

curl 'https://trackerv2.marketingplanet.global/api/v1/me' \
  -H 'Authorization: Bearer tk_live_YOUR_KEY'

const response = await fetch('https://trackerv2.marketingplanet.global/api/v1/me', {
  headers: {
    Authorization: 'Bearer tk_live_YOUR_KEY',
  },
});

const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result.data);

import requests

response = requests.get(
    "https://trackerv2.marketingplanet.global/api/v1/me",
    headers={"Authorization": "Bearer tk_live_YOUR_KEY"},
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result["data"])

{
  "data": {
    "user": {
      "id": "64b7f0c2a1e4d5f6a7b8c901",
      "name": "Alex Rivera",
      "email": "alex@acmeretail.com"
    },
    "apiKey": {
      "id": "66a1c3e5f7a9b1c3d5e7f901",
      "name": "Reporting script",
      "prefix": "tk_live_3f9a1c7e2b40",
      "scopes": [
        "read",
        "write"
      ],
      "expiresAt": "2027-01-04T09:00:00.000Z"
    },
    "plan": {
      "key": "growth",
      "maxApiKeys": 3,
      "requestsPerMinute": 300
    }
  }
}

A missing, wrong, revoked or expired key returns 401 with codes such as api-key-missing or api-key-revoked — see common errors.

Read only vs read and write

A read-only key calling a write endpoint gets 403 insufficient-scope. Use read-only keys for dashboards and reports; give write access only to scripts that need it.

Project permissions

On top of the key’s access, each project endpoint checks your role in that project — the same permissions the project owner sets under Members in the dashboard. Owners have them all.

• A project you cannot open at all returns 404 not-found, so the API never reveals that it exists.
• A project you can open, but without the permission an endpoint needs, returns 403 with the permission in the code, such as flag-changeSettings.
• Security findings are left out of every response unless you can view security.

Account endpoints — /me, listing and creating projects, webhooks and jobs — act on your own account and need no project permission.

Plans and limits

API access is part of your plan. The request limit is per account across all your keys, over a rolling minute.

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Plan limits such as project count, pages and check intervals apply to API calls exactly as in the dashboard. See rate limits.

Expiry and revocation

• Expiry. An expired key returns 401 api-key-expired. Create a new one; expired keys cannot be extended.
• Revoking. Revoke a key from your profile at any time. It stops working immediately.
• Password changes. Changing or resetting your password revokes all your API keys and pauses your webhooks, so nothing set up with the old password keeps working. Create new keys and resume webhooks afterwards.
• Plan changes. If you move to a plan with fewer keys, your newest keys keep working and older ones return 403 api-key-over-plan-limit until you revoke some or upgrade. Without API access on your plan, every call returns 403 plan-required.
• Invalid keys. Requests with an invalid key are limited per IP address. After repeated failures that IP gets 429 for a while, even with a valid key.

Keeping keys safe

• Treat a key like a password. Keep it in an environment variable or a secrets manager, not in source code.
• Never put a key in a website, browser extension or mobile app — anyone can read it there. Call the API from your server instead.
• Use one key per integration, with the narrowest access it needs, so you can revoke one without breaking the others.
• If a key leaks, revoke it straight away and create a new one.