Keys and environments | Truvo Partners docs

Every request carries an API key, and Truvo reads the integration, the environment, and the customer from it. 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.

Get a key

Sign up at the portal, then create a sandbox key on the Developer sandbox page under Keys. It starts with trv_sandbox_.

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. Every request to an API operation also sends Truvo-Version, the revision that your code is built for. See Versions and changes.

Sandbox and live keys

Every key is an API key. Its prefix sets its environment, sandbox or live, and the environment is the only difference between two keys. The two environments, sandbox and live, share one base URL, https://api.truvo.com/v1/. 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 returns synthetic results instead of asking carriers, and it applies the same contract, validation, and authority rules as live, with one exception: the sandbox accepts any US phone number, while a live request with a number that nobody could answer, such as one in the 555-0100 to 555-0199 range, fails with 422.

A sandbox key never reads live records, and it never causes a live effect.
Sandbox quotes carry the evidence label mock. Their coverage conditions include Sandbox premium. Not a carrier price.
The sandbox covers the same states as live, and its quotes name the carriers that quote the request’s state live. The prices are made up.

What the sandbox returns

Every quote request that the sandbox accepts completes with one quote. Its status is completed, its status_details.reason is quoted, and its one quote is active, with a continue_on_carrier_site action that opens a Truvo sandbox page. The API reference shows a recorded answer for each line.

You can get these answers in the sandbox:

To get	Send
A completed request with one quote	Any request that the line’s schema accepts, in a state that `GET /v1/capabilities` lists.
`422` `needs_information`	A request without a required field. `field_errors` lists each missing field.
`422` `invalid_input`	A value that the schema refuses, a state that capabilities doesn’t list for the line, or a `quote_disclosure_version` that isn’t the current one.
The same request again	The same `Idempotency-Key` and the same body. See Retry safely with request keys.
`409` `request_key_reused`	The same `Idempotency-Key` with a different body.
`400` `invalid_version`	A request without the `Truvo-Version` header.
`401` `authentication_failed`	A key that isn’t valid.
An entry in `assumptions`	A request that leaves out an optional field for which Truvo applies a default. The request pages list each default.
A signed webhook delivery	`POST /v1/event-subscriptions/{id}/test`, or a quote request while a subscription lists its events. See Webhooks.
An expired quote	Wait until the quote’s `availability.expires_at`, 30 days after Truvo created it. The quote then reads `inactive` with the reason `expired`, and Truvo sends `quote.expired`.

The sandbox doesn’t return declines, offline_quote outcomes, several quotes for one request, quotes that arrive over time, or a request that ends completed with no_quotes, offline_quotes_only or partly_quoted, incomplete, failed or action_required. Handle them from the status tables in Get quote results and Why did a request finish with no quotes?.

Live

Live traffic needs Truvo’s approval. To get it, an owner or admin of your organization books a call from the Go live page of the portal. After the call, Truvo approves your organization and issues your live keys, and the portal’s Keys page lists them. You can’t create a live key yourself.

While live access is waiting for approval, a live key gets 200 from GET /v1/capabilities with no capabilities and access.live set to not_approved. MCP initialize, tools/list, get_capabilities, and request_callback remain available, and the key can still call POST /v1/callback_requests. Its other requests to key-protected routes that are on return 403 live_access_not_approved with the reason pending_review, unless the address is rate limited. Other MCP tool calls return that answer as a tool error with isError: true. Public routes stay unchanged.

Once Truvo approves live access, a live key reads access.live as approved, and capabilities lists the lines and actions that key can use. Truvo can suspend live access later. A suspended live key returns 403 organization_suspended with the retry action contact_support.

Keys and authority

A key proves which integration is calling, and Truvo checks the integration’s authority over each customer separately. A resource that doesn’t exist and one outside your authority get the same 404. A live key whose live access is waiting for approval gets the shared 403 on a key-protected route that is on, unless the address is rate limited.

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.