Skip to main content

Getting started — using the API

This is the front door for the API track. It takes you from "I have API credentials" 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 API credentials. Sign in (or sign up) at the preview app, then mint a client_id/client_secret from the Account menu → API Keys → New Key (detail). The client_secret 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 credentials will not authenticate against production and vice versa; the switcher above keeps the curl snippets aligned with whichever world your credentials were minted on.

2. Make your first call​

Exchange your credentials for a short-lived access token and save it for the rest of this page:

export TRAKRF_ACCESS_TOKEN=$(curl -s -X POST "$BASE_URL/api/v1/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
        "grant_type": "client_credentials",
        "client_id": "6f1c2a8e-7d3b-4e90-9a11-2c4d5e6f7a8b",
        "client_secret": "trakrf_9f8e7d6c5b4a39281706f5e4d3c2b1a0ffeeddccbbaa99887766554433221100"
      }' | python3 -c "import json,sys; print(json.load(sys.stdin)['access_token'])")
# Or, if jq is installed: ... | jq -r '.access_token'

Access tokens live 15 minutes; re-exchange when one expires. Full detail: Authentication → Get an access token.

The /api/v1/orgs/me endpoint returns the organization your credentials are 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 access token authenticates against the right environment. Use an API-credential access token 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_ACCESS_TOKEN" \
     "$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.