> ## Documentation Index
> Fetch the complete documentation index at: https://api-doc.track.graviton.ma/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and access

> Authenticate with scoped API tokens, manage token permissions, and understand access and permission errors.

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:

```http theme={null}
Authorization: Bearer YOUR_API_TOKEN
```

```http theme={null}
Authorization: YOUR_API_TOKEN
```

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.

<Note>
  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.
</Note>

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

| Permission | API areas |
| - | - |
| `account:read` | Account information, account permissions, and login history (`/me`, `/me/permissions`, `/login-history`) |
| `users:read` | Reading account users |
| `users:write` | Creating and changing account users |
| `objects:read` | Listing and reading objects (`/objects`, `/me/objects`, batch reads) |
| `objects:write` | Creating, editing, activating, deactivating, and assigning objects |
| `tracking:read` | Positions, status, engine hours, history, routes, stops, drives, mileage, and object events, sensors, and services |
| `commands:read` | Reading queued commands and their status |
| `commands:write` | Queueing commands, including engine immobilize and remobilize |
| `resources:read` | Reading places, people and groups, event rules, maintenance, sensors, and templates |
| `resources:write` | Creating, changing, and deleting those managed resources |
| `reports:read` | Generating reports, downloading reports, and reading report definitions and event logs |
| `reports:write` | Creating, changing, and deleting saved report definitions |
| `admin:read` | Reading administrative information |
| `recovery:write` | Recovery operations |

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

| Operation | Requirement |
| - | - |
| Protected API requests | Valid token, API access enabled, active and unexpired account |
| Create objects | Object-add permission and an available object slot |
| Edit or deactivate objects | Object-edit permission |
| Write operations | Account with write access |
| Trip history | `history` capability for subaccounts |
| Places | `places_control` capability for subaccounts |
| Event rules | `event_notifications` capability for subaccounts |
| Reports | `reports` capability for subaccounts |
| Engine control | `stop_engine` capability for subaccounts |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.