Authentication

All requests to the API are authenticated by providing your API Token, which can be found under the API Tokens section in your account settings.

The API Token must be provided under the Authorization HTTP Header using the keyword Token in front of your actual token:

Authorization: Token abc123abc123abc123

Supported Token Auth Patterns

• API access tokens (Bearer) — issued from the TelemetryOS console for service-to-service or scripted access; presented in Authorization: Bearer .
• OAuth2 / OIDC (Enterprise) — used when integrating user identity / SSO flows; tokens follow standard OAuth2 patterns (access + refresh).
• Per-device / device enrollment tokens — used during device registration (console-issued). Certificate-backed device identity and mTLS are on the roadmap.

Key Token Controls (current GA)

• Tokens issued and revocable from the console.
• Role-based scopes enforced in the control plane (admin, content manager, viewer).
• All API traffic required to use HTTPS/TLS.

Best Practices

1. Always use HTTPS and verify certs.
2. Apply least privilege: create tokens with the minimal role/scope and limited lifetime.
3. Rotate tokens regularly and revoke immediately on compromise.
4. Store secrets securely (vaults/secret managers), not in code or public repos.
5. Use short-lived tokens where possible and use refresh tokens or automation to renew.
6. Audit token usage via console activity logs and review memberships/keys periodically.
7. For device fleets, follow network guidance: isolated VLAN, outbound-only egress, and limit inbound exposure.