> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.truvo.com/llms.txt.

# Keys and environments

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:

```http
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](/guides/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.