Authentication

The TOVR REST API authenticates with the OAuth 2.0 client-credentials grant. You exchange a client application's credentials for a bearer token, then send that token on each request. This is the TOVR-REST-specific flow; shared bearer conventions are in API conventions.

1. Get credentials

Create a client application under Settings → Developer in the TOVR dashboard to obtain a client_id and client_secret. The secret is shown once — store it securely.

2. Exchange for a token

POST /api/v1/oauth2/token, form-encoded:

curl -X POST https://tovr.eu/api/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

A JSON body (Content-Type: application/json) with the same three fields is also accepted. Send each parameter once — a repeated parameter is rejected. HTTP Basic client authentication (client_secret_basic) is not supported; send the credentials in the body.

Response:

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600
}

expires_in is 3,600 seconds (1 hour). It was 30 days until #3759; a bearer token that lives for a month is a month of exposure after a leak, and nothing revoked it. Only client_credentials is supported — any other grant_type is rejected.

3. Call the API

Send the token as a bearer header:

curl https://tovr.eu/api/v1/shipments/SHIP_ID \
  -H "Authorization: Bearer <access_token>"

The platform validates the token and injects your organization and client context into the request. You never send an org identifier in the body or headers — it is inferred from the token. Re-request a token before it expires; there is no refresh grant.

Errors

Standard codes apply (see API conventions). A missing or invalid token returns 401; a malformed token request (grant_type other than client_credentials) returns 400.