Authentication

The Client API 2026-09 uses OAuth2 bearer tokens. Every request must carry a valid access token with the client-api scope:


Authorization: Bearer <access_token>
Accept: application/json

Access tokens last 1 hour and are issued to the App of your account with the OAuth2 client_credentials grant. All resources are those of the client account that owns the App.

Getting a token

Create your App

Log into the platform and open Settings → API App (/client/api-app). Create the App: you get a client_id and a client_secret.

One active App per user; it can be revoked at any time (tokens already issued stop working immediately).
On platforms that are not self-service, the page requires at least 3 validated documents on the account.

Request a token


curl -X POST https://<subdomain>.spedisci.online/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=<client_id>" \
  -d "client_secret=<client_secret>" \
  -d "scope=client-api"


{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}

Call the API


curl https://<subdomain>.spedisci.online/api/2026-09/carriers \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"

Cache the token and reuse it until it expires (expires_in seconds). Request a new one when you receive 401 unauthenticated. Do not request a token for every API call.

Token validation

On every request the API:

validates the bearer token (signature, expiry, revocation of the token and of its App);
requires the client-api scope;
resolves the owner of the App and their client account, and checks both are active and the owner has the client role.

HTTP	`error.code`	Cause
`401`	`unauthenticated`	Token missing, malformed, expired, revoked, or its App was revoked
`403`	`insufficient_scope`	Token without the `client-api` scope (e.g. an administrator App token)
`403`	`account_disabled`	User or client account not active
`403`	`client_role_required`	The user is not a client user

See Conventions & Errors for the error envelope.

Keep client_secret and tokens on the server side. Never embed them in a mobile or browser app or in public repositories.