Authentication
Every request to Unwired Labs' APIs must be authenticated with a scoped access token. Keep tokens server-side and rotate them regularly.
Each request to Unwired's APIs needs to be authenticated with an access token.
We recommend calling these APIs from your server backend rather than from public-facing code such as JavaScript running in a browser or a mobile app, since access tokens used this way are visible to anyone inspecting the request and can be copied and reused from anywhere. If you need to call an API directly from a public-facing client, proxy the request through your own backend so the token itself is never exposed. Generate access tokens on your User Dashboard, create a separate token for each application, label them accordingly - e.g. "my server" - and reissue these tokens frequently to prevent misuse.
Access Token Scopes
Each access token has a type and a set of scopes (permissions), written as group:action - for example geolocation:locate. Choose them when you create or update a token on the User Dashboard. A token can only call operations that match its type and its selected scopes.
- Data access token (prefix
pk.) - calls product APIs. Data tokens created before scopes were introduced are unscoped and keep access to all data APIs. - Account access token (prefix
sk.) - manages account resources and cannot call data APIs. The full secret is shown only once, when the token is created.
Data API scopes
Unwired Labs data tokens can be scoped for the following groups:
| Group | Scopes |
|---|---|
| Geolocation | geolocation:locate |
| Geocoding | geocoding:forward, geocoding:reverse, geocoding:autocomplete, geocoding:nearby, geocoding:lookup, geocoding:timezone |
| Maps | maps:tiles:vector, maps:tiles:raster, maps:static |
Account API scopes
Account access tokens can be scoped for account resources:
| Group | Scopes |
|---|---|
| Overrides | overrides:read, overrides:write |
| Balance | balance:read |
| Token management | tokens:create, tokens:update, tokens:revoke (coming soon) |
| Reports | reports:read (coming soon) |
A scope can only reduce access. Your plan, product enablement and balance still apply. A token that does not carry the scope required by an endpoint is rejected with HTTP 403.
An unscoped data token keeps access to every data API available to the account, including APIs launched later. An explicitly scoped token must be updated before it can use a newly launched API.
Security Best Practices
Secure your access tokens to avoid abuse of your account. We recommend:
- Use scopes for least privilege. Grant each token only the permissions it needs. See Access Token Scopes.
- Use a separate token for each application, and rotate tokens regularly. Rotate immediately if you notice usage you don't recognize, or when a token has been used in a public app.
- Store tokens safely. Treat account access tokens like passwords: they manage account resources and their secret is shown only once. Keep tokens in a password manager or secrets vault, and never commit them to source control.
- Keep tokens server-side. Call the APIs from your backend, and proxy requests from browsers or mobile apps through it so the token is never exposed to end users.