> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryoto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API authentication

> Get a refresh token from the OTO dashboard, exchange it for a one-hour access token, and send it as a Bearer header on every API call.

Two tokens. One you keep, one you throw away every hour.

## Get your refresh token

In the dashboard, go to **Settings → API Integrations** and press **Connect**. That produces your `refresh_token`.

It is **permanent**, and it is the only long-lived credential you hold. It cannot be used to call anything except the token endpoint.

> [!WARNING]
>
> **Treat the refresh token as a password**
>
> It does not expire, so a leaked one stays useful to whoever has it until somebody notices and regenerates it.
>
> It belongs in a secrets manager or an environment variable — never in client-side code, a mobile app bundle, a repository, a support ticket or a screenshot. Anything that reaches a browser can be read by the person using that browser.

## Exchange it for an access token

`POST /rest/v2/refreshToken` Free+

```json theme={null}
{ "refresh_token": "<your permanent token>" }
```

The response carries an `access_token` with a lifetime of **one hour**. Send it on every other call:

```text theme={null}
Authorization: Bearer <access_token>
```

> [!TIP]
>
> **Cache the access token; do not fetch one per request**
>
> A token is valid for an hour, so a job that calls the API a thousand times in that hour needs one token, not a thousand.
>
> The pattern that holds up: keep the token and its expiry in memory, refresh when it is within a few minutes of expiring, and refresh again on a 401 rather than assuming your clock and theirs agree. Requesting a fresh token per call is the single most common way an integration becomes slow.

## Check the connection

`GET /rest/v2/healthCheck` Free+

Confirms the platform is reachable and responding. Worth wiring into your own monitoring, so that when something breaks you already know which side it broke on.

## The sandbox

A separate environment with its own account, its own token and test carriers, at `https://staging-api.tryoto.com`. Same paths, same shapes.

> [!NOTE]
>
> **Build against the sandbox, but test the switch**
>
> The sandbox is where you create orders that do not become real parcels and bookings that do not become real invoices. Nothing else is safe to iterate against.
>
> The failure to plan for is the cutover: production has different carrier contracts, different hubs and different codes. A configuration value hard-coded during development is the classic first-day-live incident, so keep every environment-specific value in configuration from the first commit.

## Plan availability

Endpoints are gated by subscription tier, and some also require an add-on. Every endpoint in the [index](https://docs.tryoto.com/developers/rest-api-reference.md) carries the lowest plan that includes it.

| Tier | What it opens up |
| - | - |
| Free+ | Orders, shipments, printing, tracking, products, carrier lookup, national address. Enough to run a working integration end to end. |
| Starter+ | Webhooks, your own carrier contracts, brands, returns automation, OTO FLEX, and Stock Management with the WMS add-on. |
| Scale+ | Forcing order status from your side, customer-notification history, and delivery estimation including the AI-predicted dates. |
| Pro+ | Pre-commit availability checks, and unlimited sales channels. |
| Enterprise+ | Carrier-level shipment tracking, unlimited carrier contracts, and **branch** pickup locations. |

> [!NOTE]
>
> **Ship-from-store over the API is an Enterprise capability**
>
> Pickup locations can be created on every plan, but only as **warehouses**. Creating one of `type: "branch"` — a shop that also ships — is Enterprise only.
>
> If your plan is to make stores fulfill orders programmatically, that is the line to check before you design around it. See [Hubs Management](https://docs.tryoto.com/modules/hubs-management/overview.md) for what a branch is and why it matters.

## Related

* [Webhooks](https://docs.tryoto.com/developers/webhook-events.md) — being told instead of asking.
* [Endpoint index](https://docs.tryoto.com/developers/rest-api-reference.md) — the full surface.


## Related topics

- [Users, roles & permissions](https://docs.tryoto.com/platform/users-roles-and-permissions.md)
- [Security & compliance](https://docs.tryoto.com/platform/security-and-compliance.md)
- [REST API reference](https://docs.tryoto.com/developers/rest-api-reference.md)


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