Skip to main content

Getting started — using the API

This is the front door for the API track. It takes you from "I have an API key" to "I called the TrakRF API and got a 200 back" using only standard HTTP tools, then hands off to the API Quickstart for the rest of the round-trip (CRUD, error catalog, Postman, codegen). It mirrors the UI quickstart — pick whichever track matches your integration plan.

What you'll need​

  • A TrakRF account and an API key. Sign in (or sign up) at the preview app, then mint a key from the Account menu → API Keys → New Key (detail). The token is shown once at creation — copy it immediately.
  • 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 preview docs. Examples on this page target https://app.preview.trakrf.id — the app host that matches this docs site.

Environment: preview

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

export BASE_URL=https://app.preview.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. Make your first call​

Save your API key to an environment variable for the rest of this page:

export TRAKRF_API_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

The /api/v1/orgs/me endpoint returns the organization the API key is scoped to. It's the canonical "tell me about myself" probe — requires no specific scope, depends on no prior data, and confirms end-to-end that your key authenticates against the right environment. Use an API key here — /orgs/me rejects session JWTs from the web app, even though most other public endpoints accept them. See Private endpoints → Response shape: /orgs/me for the precise rule.

curl -H "Authorization: Bearer $TRAKRF_API_KEY" \
     "$BASE_URL/api/v1/orgs/me"

A successful response looks like:

{
  "data": {
    "id": 42,
    "name": "Acme Logistics",
    "scopes": ["assets:read", "assets:write", "tracking:read"],
    "api_key_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

If the name matches the organization you minted the key under, you're authenticated end-to-end and ready to call anything else on the surface. The scopes array echoes the scope strings on the bearer (useful for diagnosing a later 403 forbidden without decoding the JWT), and api_key_id is the UUID of the API key — worth quoting in any support ticket. Per-field detail: Private endpoints → Response shape: /orgs/me.

Continue at the API Quickstart​

The API Quickstart picks up from here with the full round-trip: CRUD (create, read, update, delete), the error envelope and catalog, troubleshooting 401 / 429 / CORS, the Postman collection, and raw spec for codegen. Steps 1 and 2 above mirror its first two sections, so you can skim or skip ahead to §3 Round-trip: create, read, update, delete when you arrive.