Keys and environments | Truvo Platform docs

Every request carries an API key. The key tells Truvo which integration is calling and which environment the request belongs to. The API reads the environment and the customer from your key. Don’t send environment, customer, or customer_id in the query or the body, or an X-Environment, X-Customer, or X-Customer-Id header.

Send your key

Send the key in the Authorization header as a bearer token:

Authorization: Bearer trv_sandbox_...

A request without a valid key gets 401 with the error code authentication_failed.

Sandbox and live

There are two environments, sandbox and live. They share one base URL, https://api.truvo.com/v1/, and the key prefix picks the environment:

Key prefix	Environment
`trv_sandbox_`	`sandbox`
`trv_live_`	`live`

After the prefix, a key has 32 letters and digits.

The sandbox

You can get a sandbox before your organization is approved. It runs the same contract, validation, and authority rules as live. The only thing that changes is who answers: the sandbox returns synthetic results from a scenario catalog, not from carriers.

A sandbox key never reads live records, and it never causes a live effect.
Sandbox quotes carry the evidence label mock and no comparison amount. Their coverage conditions include Sandbox premium. Not a carrier price.
The sandbox controls under /v1/sandbox/ only work with a sandbox key. A live key gets 404 on those paths, and a sandbox key without authority gets 403.

Sandbox scenarios explains the controls.

Live

Live traffic needs Truvo’s approval. To see which lines and actions a key can use, call GET /v1/capabilities with that key.

Keys and authority

A key proves which integration is calling. It doesn’t prove that the integration has authority over a particular customer, so Truvo checks the two separately.

If you ask for a resource that doesn’t exist, or one that’s outside your authority, you get the same 404. The response doesn’t tell you which of the two it is.

When a service is down

If a service that Truvo needs is down, the API returns 503 with the code service_unavailable, the retry action retry, and a Retry-After header. An outage never returns authentication_failed, so you can treat a 401 as a problem with the key.