Documentation

Authentication

The Platform API is served from a single host, the same for every provider:

https://api.road.io

This never changes: a white-label dashboard domain (your branded dashboard.road.io) applies only to the dashboard, not the API. All API requests go to api.road.io.

Every request is authenticated with a bearer token in the Authorization header. Almost all endpoints are also scoped to a provider (your tenant), and require your provider ID in the Provider header. The two go together on most requests:

Authorization: Bearer <token>
Provider: your-provider-id

The bearer token authenticates the caller; the Provider header selects the provider the request acts on. Both are required together on provider-scoped endpoints, and a request missing the Provider header is rejected. Each endpoint's page in the reference marks exactly what it needs, so you never have to guess.

OAuth application tokens are the exception: an application token already identifies its provider, so those endpoints take the token on its own, without the Provider header. See OAuth applications.

The full machine-readable spec for each API is available to download from the sidebar, to generate a client, import into Postman or Insomnia, or explore in your own tools.

Who can call an endpoint

Every endpoint in the reference carries an access box. It tells you, at a glance:

  • Authorization the kinds of caller it accepts: a user session (a signed-in dashboard user), an API credential (a machine-to-machine token), or an action token (a short-lived, single-purpose token).
  • Permissions the access-control permissions the caller must hold, written as resource:level.
  • OAuth whether an OAuth application token is accepted, and the scopes it needs.
  • Rate limit how many requests are allowed in a window.

OAuth applications

Partners building on the application marketplace authenticate their users with OAuth and call the API with an application token. Endpoints that accept application tokens are marked OAuth in the reference, together with the scopes required. See the marketplace guides for the full authorisation flow.

Rate limits

Endpoints that enforce a rate limit show it in their access box, for example a number of requests per minute. Stay within the limit, and handle a 429 response by backing off and retrying after a short delay.