Skip to main content
Every protected request authenticates with an API token sent in the Authorization header. Each token carries its own set of permissions, so you can give every integration only the access it needs.

​
Send your API token

Both header formats are supported:
Always send the token in the Authorization header. Never put it in the URL or a query parameter, where it can end up in logs, browser history, and proxies. Use GET /me to identify the authenticated account and GET /me/permissions to inspect its permissions. Public API information and health endpoints do not require a token. All other documented endpoints require authentication. Never share tokens in screenshots or support messages; share the request ID instead.

​
Manage API tokens

An account can have multiple API tokens. Manage them from the API tab in the user account administration dialog. For each token, you can:
  • Copy its value to configure an integration.
  • Regenerate it. The previous value stops working immediately, so update every integration that uses it.
  • Revoke it. The token stops working immediately.
  • Assign individual permissions to limit what the token can do.
Existing API keys are automatically treated as managed tokens. They keep their exact value and receive all permissions by default, so current integrations continue to work. Review them and remove permissions they do not need.
Token creation, regeneration, permission editing, and revocation are available in the administration interface only. They are not part of the public REST API.

​
Token permissions

The users, admin, and recovery permissions are not required by the operations in this reference. Grant them only when Graviton advises it.

​
How access is evaluated

Token permissions are checked alongside, not instead of, the existing account checks. A request succeeds only when all of these allow it:
  • The token permission required by the method and route
  • Account permissions and subaccount capabilities
  • Object assignments for the account
  • Account status, API enablement, and account expiration
Object and resource access depends on account ownership and assignments. Subaccounts may have a smaller set of objects, places, or capabilities. If a token is valid but lacks the permission required by the requested method and route, the API returns HTTP 403 with the error code TOKEN_PERMISSION_DENIED. Edit the token’s permissions or use another token with the appropriate scope. A 404 for an object or resource can mean it is unavailable to the current account. Do not assume that another account’s identifier will work with your token.