API access for developers

Trakora exposes a REST + webhook API for ERP integration, custom dashboards, and third-party automations. This article covers key generation, rate limits, the OpenAPI spec, and webhook signing.

1. Generate an API key

1. Admin → API → New key.
2. Name it after the integration (Sage 300 sync, Internal BI, Slack alert bot).
3. Pick scopes — read:devices, read:positions, write:rules, etc. Scope down as much as possible.
4. Copy the key. It is shown once only. Store it in a secrets manager (Doppler, 1Password, Vault).

Keys are revocable any time; revocation takes effect immediately.

2. Authentication

Send the key as a bearer token:

GET /v1/devices
Host: api.trakora.co.tz
Authorization: Bearer trk_live_xxxxxxxxxxxx

Use HTTPS only. Plain HTTP is rejected.

3. Rate limits

Per workspace per minute:

• Free / Solo — 60 requests
• Starter — 300 requests
• Business — 1,500 requests
• Pro / Enterprise — 10,000 requests

Limits are per minute on a sliding window. 429 responses include a Retry-After header. WebSocket and webhook delivery are not counted.

4. OpenAPI / docs

The full schema lives at api.trakora.co.tz/docs (Swagger UI). The OpenAPI 3 JSON spec is at /api/docs/openapi.json.

Note — the /api/docs path on the marketing site is currently a redirect to the live Swagger UI on the API host. If you hit a 404, use api.trakora.co.tz/docs directly.

5. Webhooks

1. Admin → API → Webhooks → New.
2. URL — your HTTPS endpoint.
3. Events — device.position, alert.fired, sale.closed, excursion.opened, etc.
4. Secret — Trakora generates a secret used to sign every payload.

Each webhook request is signed with HMAC SHA-256:

X-Trakora-Signature: t=<unix-ts>,v1=<hex-hmac>

Verify by recomputing HMAC_SHA256(secret, "<unix-ts>." + raw-body). Reject if the signature doesn't match or if the timestamp is more than 5 minutes off — that prevents replay attacks.

6. Idempotency

POST endpoints support an Idempotency-Key header. We cache the response for 24 hours so retries don't double-charge or double-create.

7. SDKs

• trakora-js — official TypeScript/JavaScript SDK. npm i @trakora/sdk.
• trakora-py — community Python wrapper.
• For other languages use any HTTP client; the API is plain REST + JSON.

Still stuck?

WhatsApp +255 759 702 766 or email support@trakora.co.tz.