Skip to main content

Authentication & tokens

Every request to /api/v1/ is authenticated with a single long-lived API token issued to a MyTrafficData user account. There are no OAuth flows, no refresh tokens, no session cookies — just one header on every request.

TL;DR​

  1. Get an API token from your MyTrafficData account.
  2. Send it as Authorization: Token <your-token> on every request.
  3. Rotate it when needed; the old token stops working immediately.
Authenticated request
curl -H "Authorization: Token <your-token>" \
     https://mytrafficdata.com/api/v1/traffic/sites

Getting a token​

Tokens are managed from the API Tokens page in your MyTrafficData account (sign in to the web app and look under the user menu).

When you generate or regenerate a token:

  • The full plaintext value is shown exactly once, immediately after generation. Copy it into your secret store at that moment.
  • After you leave the page, the value is masked (abcd1234…wxyz) and cannot be recovered. If you lose it, regenerate a new one.

:::warning Permission required Your account needs the can_use_api permission to be issued a token. If the API Tokens page doesn't show a generation button, contact your account administrator. :::

Using the token​

Send the token in the Authorization header, prefixed with the word Token and a single space:

GET /api/v1/traffic/sites HTTP/1.1
Host: mytrafficdata.com
Authorization: Token <your-token>

The same header format works for every endpoint under /api/v1/.

Language examples​

Python (requests)
import requests

TOKEN = "<your-token>"
headers = {"Authorization": f"Token {TOKEN}"}

r = requests.get(
    "https://mytrafficdata.com/api/v1/traffic/sites",
    headers=headers,
)
r.raise_for_status()
JavaScript (fetch)
const TOKEN = "<your-token>";

const r = await fetch("https://mytrafficdata.com/api/v1/traffic/sites", {
  headers: {Authorization: `Token ${TOKEN}`},
});
if (!r.ok) throw new Error(await r.text());
curl
curl -H "Authorization: Token <your-token>" \
     https://mytrafficdata.com/api/v1/traffic/sites

Token rotation​

Tokens don't expire on a clock — they stay valid until you rotate or revoke them. To rotate:

  1. Open the API Tokens page in your MyTrafficData account.
  2. Click Regenerate.
  3. Copy the new value.
  4. Update your secret store / deployment config.
  5. Restart any long-running processes using the old value.
warning

Regeneration is immediate and irreversible — the previous token stops working the moment the new one is issued. Schedule rotations during a maintenance window if you can't switch over atomically.

We recommend rotating on a fixed cadence (every 6–12 months) and immediately after any suspected leak.

Storage best practices​

  • Never commit tokens to source control. Use environment variables, a secret manager (AWS Secrets Manager, HashiCorp Vault, etc.), or your platform's equivalent.
  • Use a separate user per integration if possible. Each integration gets its own token; revoking one doesn't break the others.
  • Treat the token like a password. It grants every permission your user account has — including the ability to read measurement data, create exports, and dispatch device commands.
  • Audit periodically. The MyTrafficData dashboard shows the timestamp of your token's last use; investigate unexpected usage.

Failure modes​

Authentication failures return HTTP 401 Unauthorized or 403 Forbidden with a JSON body carrying a detail field. See Errors for the full response-shape catalog.

Missing or malformed header​

GET /api/v1/traffic/sites
401 Unauthorized
{
  "detail": "Authentication credentials were not provided."
}

Add the Authorization: Token … header and retry.

Wrong or revoked token​

GET /api/v1/traffic/sites
Authorization: Token deadbeef00000000
401 Unauthorized
{
  "detail": "Invalid token."
}

Regenerate from the MyTrafficData dashboard, update your secret store, retry.

Authenticated but not authorized​

403 Forbidden
{
  "detail": "You do not have permission to perform this action."
}

The token is valid but your account doesn't have permission to call this endpoint. Most commonly: the can_use_api permission is missing on your user, or you're trying to access a resource owned by a different account. Contact your account administrator.

Summary checklist​

  • ✅ One token per user, sent as Authorization: Token <value>.
  • ✅ Plaintext shown exactly once at generation — copy it then.
  • ✅ Rotate by regenerating; the old token is killed immediately.
  • ✅ Store tokens in a secret manager, never in source control.
  • ✅ Use one user/token per integration so a single revoke doesn't take down everything.
  • ✅ can_use_api permission required on the user — gate enforced by the server.