# Authentication & Scopes

Every v5 request uses a bearer token:

```http
Authorization: Bearer <token>
```

Tokens are scoped and can optionally expire. Create the first token in the
dashboard under **Settings -> Integrations -> API**. A token with
`tokens:manage` can create and revoke additional v5 tokens through the API.

## Response envelope

Successful responses are wrapped in `data`.

```json
{
  "data": {
    "id": 12345,
    "status": "incomplete"
  }
}
```

List endpoints also include `meta` and `links` for pagination.

Errors are wrapped in `error` and include a stable `code`.

```json
{
  "error": {
    "code": "validation_failed",
    "message": "The given data was invalid.",
    "details": {
      "packages.0.weight": ["The packages.0.weight field is required."]
    }
  }
}
```

Branch on `error.code`, not the message text.

## Pagination

List endpoints use `page` and `per_page`. The default `per_page` is 25 and the
maximum is 100.

```http
GET /shipments?page=2&per_page=50
```

## Scope vocabulary

| Scope | Purpose |
|  --- | --- |
| `tokens:manage` | Manage API tokens. |
| `addresses:validate` | Validate addresses before creating shipments. |
| `rates:read` | Quote shipping rates. |
| `shipments:read` / `shipments:write` / `shipments:void` | Shipment lifecycle. |
| `labels:create` | Purchase and combine labels. |
| `pickups:write` | Schedule and cancel carrier pickups. |
| `tracking:read` / `tracking:subscribe` | Tracking lookups and notifications. |
| `batches:read` / `batches:write` / `batches:process` | Bulk batch flow. |
| `ltl:read` / `ltl:write` | LTL freight quotes and bookings. |
| `products:read` / `products:write` | Product catalog updates. |
| `products:classify` / `products:approve` | DDP classification and approval. |
| `orders:read` / `orders:write` | Order CRUD. |
| `boxes:read` / `boxes:write` | Box preset CRUD. |
| `automation:read` / `automation:write` | Rules, filters, lists, tags, and scheduled automations. |
| `billing:read` | Statements and transactions. |
| `credits:read` / `credits:write` | Credit balance and top-ups. |


Each operation in the [API Reference](/openapi) lists its required
scope.