# Authentication & Scopes

External API clients authenticate every v5 request with 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**.

The entire authenticated v5 group also accepts a logged-in dashboard session in
place of a bearer token (`EnsureFrontendRequestsAreStateful` + `auth:sanctum` wrap
every route in `routes/api.php`'s v5 group) — session auth passes every route's
scope check, since Sanctum's session guard always reports the requested scope as
granted. Token management (`POST/GET/DELETE /api/v5/tokens`) is further
restricted on top of that: it's the one v5 endpoint with an extra
primary-account-holder gate, so sub-user dashboard sessions receive `403` with
code `forbidden` there specifically. A token with `tokens:manage` can create and
revoke additional v5 tokens through the API as a bearer client.

## 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.