Copy page

Documentation

Authentication

Authentication

Every request to the AirTrack API is authenticated with a bearer token:

Code
Authorization: Bearer aapk_pdn_…

A credential is a connection. It carries a set of scopes (the capabilities it's allowed to use) and is owned by either a user or a partner. How you obtain a token depends on what you're building — but once you have one, every call works the same way.

Which integration are you building?

A connected device and a per-user integration both obtain a token through the pairing-code flow. A B2B partner is issued a token directly.

Getting a token

User-owned connections

For devices and per-user integrations. The owning user pairs your client from the AirTrack app; the pairing grants it a set of scopes fixed by the server. This requires the user to have an active AirTrack premium subscription.

1. The user creates a pairing code. In the AirTrack app, the user generates a 6-digit code granting the standard integration scopes — aq:read, aq:routes and routes:plan. The code is valid for 60 seconds and can be used once.

2. The user enters the code into your client.

3. Your client redeems the code for a token. No authentication is required — the code is the proof. Supply a name to identify the connection:

   Code
   curl -X POST https://api.airawarelabs.com/v1/connections/token \
     -H "Content-Type: application/json" \
     -d '{ "code": "048213", "name": "Living-room display" }'
   # → { "connection_id": "…", "name": "Living-room display",
   #     "scopes": ["aq:read", "aq:routes", "routes:plan"], "token": "aapk_pdn_…" }

4. Store the token securely and use it for every subsequent call.

The scopes are fixed by the server when the code is minted — a client cannot request or escalate its own scopes. Premium is re-checked on every call that computes air quality or submits a route plan, so those start returning 403 if the user's subscription lapses. Reading your quota and polling for a plan result are not premium-gated — a lapsed user can still collect a result they already paid for.

See POST /v1/connections/token in the API reference.

Partner connections

For B2B integrations — scoring routes or enriching data at scale — tokens are issued directly under a partner agreement rather than through pairing. Get in touch at support@airawarelabs.com to set up a partner account. Your token carries the scopes agreed for your integration and stays valid while your partner account is active.

Authenticating requests

Send the token as a bearer header on every request:

Code
curl -X POST https://api.airawarelabs.com/v1/airquality/score \
  -H "Authorization: Bearer aapk_pdn_…" \
  -H "Content-Type: application/json" \
  -d '{ "lat": 51.5, "lon": -0.12 }'
# → { "score": 82, "ttl": 3600 }   # Clean Air Score: 100 = cleanest, 0 = worst

Each endpoint requires a specific scope. If your token lacks it, the call returns 403. Tokens are environment-specific — the segment after aapk_ (pdn, tst) tells you which environment issued it.

Scopes

Scopes name capabilities, not consumers. They're fixed when the connection is created — by the server at pairing, or with a partner token — and can't be changed by the client.

Scope	Allows
aq:read	Read air quality for points and forecasts (current and historical).
aq:routes	Enrich a route you supply with per-waypoint air quality.
routes:plan	Plan lower-exposure routes between two points.

Token security

• The raw token is shown once, when the connection is created — store it securely and never expose it in client-side web code. We keep only a hash.
• Revoking a connection (from the AirTrack app) invalidates its token immediately — the next call returns 401.
• To rotate a token, revoke the connection and pair again.

Error responses

The two you'll meet most often when getting authentication right:

Status	Meaning
401	Missing, unknown or revoked token; or an invalid/expired pairing code.
403	Your token isn't permitted to perform that operation — usually a missing scope; on the endpoints that compute air quality or submit a plan, also a lapsed premium plan. Causes vary per endpoint; see its own description.

See Errors for the full status-code reference, the error envelope, and a robust retry pattern for rate limits.