Authentication
Every request to the Ototo API is authenticated with a subscription key. This page covers how to send it, how it relates to environments, and what account permissions control access to specific endpoints.
Sending your subscription key
Attach your key as a subscription-key query string parameter on every request, regardless of HTTP method:
GET https://api.ototo.be/v1/CarDetails/{carDetailId}?subscription-key=YOUR_KEYPOST https://api.ototo.be/v1/Calculate?subscription-key=YOUR_KEY
Content-Type: application/jsonThe API is fronted by Azure API Management, which also accepts the key via the standard Ocp-Apim-Subscription-Key header instead of the query parameter — useful if you'd rather keep the key out of URLs and access logs. The query parameter is the form documented here and guaranteed to work; confirm header support with your Ototo contact if you rely on it.
Misuse of the API may result in your key being invalidated. Keep it server-side, out of logs, and out of any client-side code or public repository.
Environments
Each environment has its own subscription key and its own data — nothing is shared between them. Requests authenticated with an acceptance key will not work against production, and vice versa.
| Environment | Base URL | Notes |
|---|---|---|
| Acceptance / sandbox | https://ototo-acc.azure-api.net/v1/ |
For development and testing. May change; you'll be notified of impacting changes. |
| Production | https://api.ototo.be/v1/ |
Stable. Breaking, non-backwards-compatible changes ship under a new version number rather than changing this contract in place. |
Primary and secondary keys
Every subscription is issued a primary and a secondary key, the standard Azure API Management key pair. Both are valid at the same time, which lets you rotate credentials without downtime:
- Switch your integration to the secondary key.
- Ask your Ototo contact to reissue the primary key.
- Switch back, or simply keep using whichever key is currently convenient — both remain active.
Account status and calculation access
Two conditions gate access, and both are configured on your subscription by Ototo:
- Active subscription — required for every endpoint. An inactive subscription is rejected outright.
- Calculation access — required in addition, specifically for
POST /CalculateandGET /GetTaxMatrix. A subscription can be active but not yet have calculation access enabled.
Endpoints that don't perform a calculation — Car Details, Public Link, QR Code — only require an active subscription.
Error responses
| Status | Meaning |
|---|---|
401 Unauthorized | The subscription-key is missing or invalid, your subscription is inactive, or (for Calculate / Tax Matrix) calculation access isn't enabled. |
Each endpoint's own reference page lists its remaining error responses (validation errors, not-found, etc.).
Getting credentials
Subscription keys are issued by Ototo — there is no self-service sign-up. Contact your Ototo account manager to request a key for the acceptance environment, build and test your integration there, then request a production key once you're ready to go live.
Security recommendations
- Store the key server-side only. Never ship it inside a mobile app, browser bundle, or other client-side code.
- Don't commit keys to source control, even in a private repository.
- Avoid printing the key to logs, error messages, or monitoring tools.
- Rotate periodically using the primary/secondary pair above.
- If you suspect a key has leaked, contact Ototo immediately so it can be invalidated and reissued.