Docs

Scopes

A scope is one permission your app asks for. The operator, or the user, approves it; the API then lets your app do that and nothing more.

Scope reference

Scoperead/writeGrant typesDescriptionOperations
trips:readreadclient_credentialsauthorization_codeRead trips, with their route, driver, vehicle, stops, progress and passenger counts.
trips:writewriteclient_credentialsauthorization_codeCreate, change, cancel and reschedule trips, assign a driver and vehicle, and rewrite a trip’s stops. No delete. A tenant admin approves it.
6 operations
routes:readreadclient_credentialsauthorization_codeRead routes and their readiness.
drivers:readreadclient_credentialsauthorization_codeRead drivers.
vehicles:readreadclient_credentialsauthorization_codeRead vehicles.
stops:readreadclient_credentialsauthorization_codeRead stops.
webhooks:managewriteclient_credentialsCreate, change, enable, disable, delete and test your app’s webhook subscriptions, rotate their secrets and read their delivery log. It reads only what your app owns. Client-credentials tokens only. A tenant admin approves it.Also reads your app’s own subscriptions and delivery log.
14 operations
offline_accessprotocolauthorization_codeLets an authorization-code grant return a refresh token. It opens no data.none

How scopes work

  • Read and write. *:read scopes read data. trips:write and webhooks:manage change data: they are sensitive and a tenant admin has to approve them. webhooks:manage also reads your own subscriptions so you can manage them; trips:write does not open any read route, so ask for trips:read too.
  • A scope is an upper limit. A token holds your app’s scopes, cut down to what the operator accepted (and, for a user token, to what that user may do). A narrowed install takes effect on the next request.
  • Not reachable at all. Billing, user and role management and platform administration are not part of any scope. Trips cannot be deleted and passenger attendance cannot be written through the API.
  • offline_access only asks for a refresh token. tenant:connect is for partner apps: it lets client_credentials run inside installed tenants, and it is never carried by an access token.
  • Ask for the smallest set. The operator sees each scope in plain words and may untick any of them.