Skip to content
Track That Ride
Menu

API documentation

Authentication

Every Track That Ride API request is authenticated with an API key sent as a Bearer token in the Authorization header. Each key belongs to one company, carries read, write or delete permissions per resource, has its own rate limit, and can be rotated or revoked. Browser streams use short-lived tokens instead of keys.

Looking for every endpoint and schema in one place? See the Full OpenAPI reference.

Sending your key

Authorization: Bearer tk_live_key_1a2b3c4d5e6f7a8b_0123456789abcdef0123456789abcdef

Keys look like tk_live_<key id>_<secret>. The key ID part lets us find the key without scanning; the whole key is stored only as a bcrypt hash, so we cannot show it to you again after it is created. Keep keys on your server, never in browser or mobile app code.

Creating, rotating and revoking keys

Company admins manage keys in the dashboard under API keys. The number of keys you can hold depends on your plan. Rotating a key issues a new secret and invalidates the old one; revoking disables it immediately. A key can also be given an expiry date.

Permissions

Each key has a list of permissions, one entry per resource, each with any of read, write and delete. Resources: rides, drivers, zones, companies, tracking, analytics, webhooks, reviews, customers.

The reference pages show the permission each endpoint needs, for example rides:write to create a delivery. A request with a valid key but without the permission gets 403: 

{ "error": "Insufficient permissions", "message": "This API key does not have 'write' permission for 'rides' resource" }

Authentication errors

StatuserrorMeaning
401Missing API keyNo Authorization: Bearer header.
401Invalid API keyUnknown or revoked key.
401API key disabledThe key has been switched off.
401API key expiredThe key’s expiry date has passed.
403Insufficient permissionsThe key lacks the permission for this resource and action.
429Rate limit exceededSee rate limits.

Tokens for event streams

EventSource cannot send an Authorization header, and an API key must never appear in a URL. To open your company’s live event stream, your server exchanges the key for a short-lived token (only the per-delivery public tracking endpoints allow cross-origin reads, so open or relay the company stream from your own server rather than from a page on another domain): 

curl -X POST https://trackthatride.com/api/v1/auth/sse-token \
  -H "Authorization: Bearer $TTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose": "tracking-events", "expiresIn": 3600}'

purpose is tracking-events (default), admin-dashboard or driver-updates; expiresIn is 300 to 7,200 seconds (default 3,600). The response is { "token", "expiresAt", "expiresIn", "purpose" }. Use it as described in real-time streams.

Customer tracking pages need no token at all: their streams are authorised by the signed tracking token in the URL.

Related