Authentication

Every request to the Pointeron API must be authenticated with an API key. This guide covers how API keys work, the two supported header formats, key scopes, and how to handle authentication errors.

API keys

API keys are created in the Pointeron dashboard under Settings » API Keys. Each key is scoped to a single organization, meaning all requests made with that key operate within that organization's data.

There are two key prefixes:

Name
sk_live_...
Type
string
Description
Production key. Use this in your deployed application. Actions performed with this key affect live data.
Name
sk_test_...
Type
string
Description
Test key. Use this during development. Test keys operate in a sandbox environment and do not affect production data.

API keys are only displayed once at creation time. Store them securely and never commit them to version control.

Authenticating requests

Pointeron supports two ways to pass your API key. Both are equivalent -- use whichever fits your integration best.

Bearer token (recommended)

Pass the key in the standard Authorization header with the Bearer scheme.

curl https://api.pointeron.com/v2/assets \
  -H "Authorization: Bearer ${POINTERON_ACCESS_TOKEN}"

X-API-Key header

Alternatively, pass the key in a custom X-API-Key header. This can be useful in environments where the Authorization header is reserved.

curl https://api.pointeron.com/v2/assets \
  -H "X-API-Key: ${POINTERON_API_KEY}"

Scopes and permissions

When creating an API key, you assign scopes that control what the key is allowed to do. A request that requires a scope not granted to the key receives a 403 Forbidden response.

Name
assets:read
Description
List and retrieve assets.
Name
assets:write
Description
Create, update, and delete assets.
Name
devices:read
Description
List and retrieve devices.
Name
devices:write
Description
Create, update, and delete devices.
Name
locations:read
Description
Query location history.
Name
locations:write
Description
Push location data points.
Name
geofences:read
Description
List and retrieve geofences.
Name
geofences:write
Description
Create, update, and delete geofences.
Name
webhooks:read
Description
List and retrieve webhooks.
Name
webhooks:write
Description
Create, update, and delete webhooks.
Name
alerts:read
Description
List and retrieve alerts.
Name
alerts:write
Description
Create, update, and delete alerts.

Organization context

All API keys are bound to the organization that created them. Every request automatically operates within that organization's data -- you do not need to specify an organization ID. If you manage multiple organizations, create a separate API key for each one.

Error responses

When authentication fails, the API returns one of the following responses:

Name
401 Unauthorized
Description
The API key is missing, malformed, or has been revoked. Double-check the header format and key value.
Name
403 Forbidden
Description
The API key is valid but does not have the required scope for this endpoint. Update the key's scopes in the dashboard.

401 Unauthorized

{
  "object": "error",
  "success": false,
  "error": "unauthorized",
  "message": "Invalid or missing API key.",
  "request_id": "req_abc123def456"
}

403 Forbidden

{
  "object": "error",
  "success": false,
  "error": "forbidden",
  "message": "API key does not have the required scope: assets:write",
  "request_id": "req_abc123def456"
}

Best practices

Use test keys during development. Switch to sk_live_ keys only in production.
Grant minimal scopes. Give each key only the permissions it needs.
Rotate keys regularly. Revoke and replace keys periodically, and immediately if a key is compromised.
Never expose keys client-side. API keys should only be used in server-to-server communication. Never include them in frontend JavaScript or mobile app bundles.