Skip to main content

Getting started — using the API

This page takes you from "I just signed up" to "I called the TrakRF API and got a 200 back" in about 10 minutes, using only standard HTTP tools. It mirrors the UI quickstart — pick whichever track matches your integration plan.

What you'll need​

  • A TrakRF account. If you were given preview credentials, you already have one — skip to step 1. Otherwise sign up at app.trakrf.id.
  • An API client of your choice — curl, Postman, HTTPie, or your language's standard HTTP library. This guide uses curl in examples.
  • 10 minutes.

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 your first API key​

  1. Sign in at the production web app.

  2. Open the avatar menu in the top-right corner and choose API Keys. (The left-nav Settings page configures devices — not keys.)

  3. Keys are scoped to the org selected in the avatar menu. If you admin multiple orgs, check the switcher first. (details)

  4. Click New key. Give it a descriptive name (e.g. "local dev"), choose scopes (scans:read alone is enough for this quickstart — the /locations/current endpoint is gated by scans:read; grant assets:read and locations:read if you plan to hit the other read endpoints), and submit.

  5. Copy the JWT immediately. It's shown once at creation time and can't be recovered later.

  6. Save it to an environment variable for the next steps:

    export TRAKRF_API_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Full detail: Authentication → Mint your first API key.

3. Make your first call​

The /api/v1/locations/current endpoint returns a snapshot of where TrakRF last saw each asset. It's cheap, requires scans:read, and gives you a live signal 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
}

The data array holds one item per asset that has ever been scanned. Each item is { asset, location, last_seen } where asset and location are the business identifiers (not integer surrogate IDs — see Resource identifiers for why).

If you get a 401, the key is malformed or not being sent in the header. If you get a 403, the body names the missing scope — for this endpoint it'll be "Missing required scope: scans:read". If you get a 429, you're being rate-limited — see Rate limits. If you're calling from browser JavaScript and getting a CORS error with no body, the API is server-to-server only (details).

All error bodies are 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 handlers against body.error.type and body.error.detail, not top-level fields. Full catalog: Errors.

4. Interpret the response​

The two key concepts integrators trip on:

  • identifier vs surrogate_id — every resource has a human-meaningful string identifier (what you see in URLs and as asset / location values above) and an integer surrogate_id (returned in full resource objects). Always key on identifier. Full convention: Resource identifiers.
  • Response envelope — every endpoint on the public surface wraps payloads in { "data": ..., ... }, including GET /api/v1/orgs/me. List endpoints add pagination metadata (limit, offset, total_count) — see Pagination, filtering, sorting.

5. Next steps​