Skip to main content

Quickstart

Goes from "I just signed up" to "I called the TrakRF API and got a 200 back" in about ten minutes, with nothing but an HTTP client.

If you're already familiar with API-key-authenticated REST APIs, the TL;DR is: mint a JWT from the avatar menu → API Keys, send it as Authorization: Bearer <jwt>, and hit $BASE_URL/api/v1/.... The full walkthrough follows.

1. Pick your environment​

You're reading production docs. Examples on this page target https://app.trakrf.id — the app host that matches this docs site.

Environment: production

If your account lives on the other environment, use the switcher above — the examples and links below will update.

export BASE_URL=https://app.trakrf.id

Preview-scoped keys will not authenticate against production and vice versa; the switcher above keeps the curl snippets aligned with whichever world your key was minted on.

2. Mint an API key​

  1. Sign in with an admin account on the production app.

  2. Open the avatar menu in the top-right corner and choose API Keys. (The left-nav Settings page is for device configuration — not key management.)

  3. If your account belongs to multiple organizations, keys are scoped to whichever org is currently selected in the avatar menu. Check the org switcher before clicking New key. See Authentication → Mint your first API key for detail.

  4. Click New key. Give it a descriptive name (e.g. "local-dev"). For this quickstart, scans:read alone is enough — the /locations/current endpoint you'll call below is gated by scans:read. Grant assets:read and locations:read if you plan to hit the other read endpoints, and assets:write for the create/update/delete walkthrough in step 4. See Authentication → Scopes for the full matrix.

  5. Pick an expiration. The Expires picker offers Never / 30 days / 90 days / 1 year / Custom. 90 days is the recommended default for production keys; see Key lifecycle before choosing Never.

  6. Submit. The full JWT is displayed once. Copy it immediately — it cannot be shown again.

  7. Save it to an environment variable:

    export TRAKRF_API_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Full detail: Authentication → Mint your first API key.

3. First read call​

GET /api/v1/locations/current returns a snapshot of where TrakRF last saw each asset. It's cheap, needs scans:read, and tells you end-to-end that your key works:

curl -H "Authorization: Bearer $TRAKRF_API_KEY" \
     "$BASE_URL/api/v1/locations/current"

A successful response looks like:

{
  "data": [
    {
      "asset": "ASSET-0001",
      "location": "LOC-0001",
      "last_seen": "2026-04-20T14:32:18Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "total_count": 1
}

Troubleshooting the first call:

  • 401 unauthorized — the key is missing, malformed, or revoked. Re-check the Authorization header.
  • 403 forbidden — the key lacks scans:read. The body names the missing scope ("Missing required scope: scans:read"). Create a new key with the right scope.
  • 429 rate_limited — you're over budget; wait the Retry-After seconds. See Rate limits.
  • Browser console error with no response body — CORS. The API is server-to-server only; call it from a backend. See Server-to-server design.

Every error response is wrapped in an error key — a 403 looks like:

{
  "error": {
    "type": "forbidden",
    "title": "Forbidden",
    "status": 403,
    "detail": "Missing required scope: scans:read",
    "instance": "/api/v1/locations/current",
    "request_id": "01JXXXXXXXXXXXXXXXXXXXXXXX"
  }
}

Write error handlers against body.error.type and body.error.detail, not top-level fields. Full catalog: Errors.

4. Round-trip: create, read, update, delete​

This walks through the write path end-to-end with an asset. It needs assets:write on the key (and assets:read if you want to verify via GET).

# Create
curl -X POST "$BASE_URL/api/v1/assets" \
  -H "Authorization: Bearer $TRAKRF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "identifier": "ASSET-QUICKSTART",
        "name": "Quickstart test asset",
        "type": "asset"
      }'

# Read it back
curl -H "Authorization: Bearer $TRAKRF_API_KEY" \
     "$BASE_URL/api/v1/assets/ASSET-QUICKSTART"

# Update
curl -X PUT "$BASE_URL/api/v1/assets/ASSET-QUICKSTART" \
  -H "Authorization: Bearer $TRAKRF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Quickstart test asset (renamed)"}'

# Delete
curl -X DELETE "$BASE_URL/api/v1/assets/ASSET-QUICKSTART" \
  -H "Authorization: Bearer $TRAKRF_API_KEY"

Each request echoes back the resource (or 204 No Content on delete) wrapped in the standard { "data": ... } envelope.

5. Alternative: Postman​

Prefer a GUI? The same API surface is available as a ready-to-import Postman collection:

  1. Download trakrf-api.postman_collection.json.
  2. In Postman, Import → File and select it.
  3. Set the collection variables:
    • baseUrl → https://app.trakrf.id/api/v1 (or https://app.preview.trakrf.id/api/v1 for preview accounts)
    • apiKey → the JWT from step 2
  4. Collection auth is preconfigured as a Bearer token referencing {{apiKey}}.

Full detail: Postman collection.

6. Raw spec for codegen​

If you'd rather generate a typed client, the OpenAPI spec is available in both formats:

Feed either into openapi-generator-cli, NSwag, oapi-codegen, etc. to scaffold client code in your language. The spec is regenerated from the Go handlers on every platform release, so the generated client stays in sync with the running service.

Next steps​