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 https://app.trakrf.id/api/v1/.... The full walkthrough follows.

Preview environment

If your account lives on the preview stack (per-PR test deploys, sales demos, every current test account), replace app.trakrf.id with app.preview.trakrf.id in every URL below. The API surface is identical; only the host differs.

1. Mint an API key​

  1. Sign in at app.trakrf.id with an admin account.

  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. Click New key. Give it a descriptive name (e.g. "local-dev"). For this quickstart, locations:read and scans:read are enough — the /locations/current endpoint you'll call below is gated by scans:read. See Authentication → Scopes for the full matrix.

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

  5. Save it to an environment variable:

    export TRAKRF_API_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Full detail: Authentication → Mint your first API key.

2. 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" \
     https://app.trakrf.id/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 will name 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.

3. 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 https://app.trakrf.id/api/v1/assets \
  -H "Authorization: Bearer $TRAKRF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "identifier": "ASSET-QUICKSTART",
        "name": "Quickstart test asset",
        "type": "generic"
      }'

# Read it back
curl -H "Authorization: Bearer $TRAKRF_API_KEY" \
     https://app.trakrf.id/api/v1/assets/ASSET-QUICKSTART

# Update
curl -X PUT https://app.trakrf.id/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 https://app.trakrf.id/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.

4. 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
    • apiKey → the JWT from step 1
  4. Collection auth is preconfigured as a Bearer token referencing {{apiKey}}.

Full detail: Postman collection.

5. 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​