> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valarhq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Use your own provider key
> Serve your Claude or OpenAI coding traffic on your organization's own Anthropic, AWS Bedrock or OpenAI API key, billed by that provider instead of Valar
If your organization already buys model capacity directly - from Anthropic, from AWS through Amazon
Bedrock, or from OpenAI - you can serve the matching ValarCode traffic on your own key. Valar routes
the request, meters the tokens, and charges you nothing for the inference. Your provider bills your
account for it. You can store one key of each kind.
**A key covers the models of its own provider, and nothing else.** An Anthropic or AWS Bedrock key
serves your Claude-tier traffic; an OpenAI key serves the OpenAI models. A Bedrock key also serves
OpenAI models when you enable **Also serve OpenAI models on this key**. Traffic to a provider you
have stored no key for keeps running on Valar-managed providers and is billed by Valar, exactly as
it was before you stored anything.
This is often called BYOK — bring your own key.
## Who it is for
Use your own key when:
* You hold commitments, credits, or negotiated rates with Anthropic, AWS or OpenAI that you want your
coding traffic to draw down.
* Your procurement or compliance process requires frontier spend to sit on your own provider account.
Stay on Valar-managed providers when:
* You want a single bill, or you have no account of your own with that provider.
* You want Valar's spend caps and failover to keep protecting your team. Both stop applying to
requests served on your key — see [What you give up](#what-you-give-up), which you should read
before you turn this on.
Using your own key is turned on per organization, by arrangement with Valar. Talk to your Valar
contact to have it enabled for yours.
## What you give up
Two guardrails stop applying to any request served on your key. Both are deliberate, and neither is
recoverable by retrying.
**No fallback onto Valar's keys. If your provider cannot serve the request, the request fails.**
Normally a request has more than one way to reach the model, on Valar's own accounts. With one key
of yours, the chain collapses to that single hop. With two keys for the same provider, both hops
are **yours**, never Valar's. This holds whichever Bedrock [endpoint](#endpoint-and-region)
your key is set to: if that endpoint fails the request, it moves to your Anthropic key. If your
provider is down, or your key is rate-limited, revoked, or wrong, the request returns an error to
the harness — Valar does **not** quietly retry it on a Valar-paid provider key. Retrying would move
the cost back onto us and put your traffic on a credential you did not choose, so we fail the
request instead.
Plan for it the way you would plan for calling the provider directly: keep enough rate limit
headroom on your own account for your whole team's coding traffic, and know that a provider
incident is now visible to your engineers.
**No spend cap. Your Valar spend limits no longer apply to this traffic.**
Valar's per-engineer monthly quotas and your organization's spend limits and credit checks exist to
stop a runaway agent from spending your money with us. They cannot govern spend that never reaches
us: on your key the tokens are billed directly to your own provider account, with no Valar-side
ceiling in front of them.
Valar's per-organization request rate limit is skipped for the same reason, so your provider
account's own rate limits are the only ones in front of this traffic.
Set your budget where the spend now lands - use your provider's own spend limits and usage alerts
on the account that owns the key. Per-engineer **pause** still works, so you can still stop an
individual engineer.
## Add, rotate, or remove your key
Once your organization is enabled, a box per provider appears under **Bring your own key** on the
**Settings - ValarCode settings** page: **Anthropic API key**, **AWS Bedrock API key** and **OpenAI API key**.
Each box carries a badge for the traffic that key serves - Claude, OpenAI, or both. You need the
organization **admin** role to change a key; any member can see whether one is set.
**Add a key**
1. Create the key on the account you want the traffic billed to - an API key in the
[Anthropic console](https://console.anthropic.com) (starts with `sk-ant-`), a **long-term**
Bedrock API key in the AWS console under **Bedrock -> API keys** (starts with `ABSK`), or an API
key in the [OpenAI platform console](https://platform.openai.com/api-keys) (starts with `sk-`).
Give it enough rate limit for your whole team.
2. Expand the box, paste the key, and click **Check & save**. Valar checks the key with the
provider before storing anything: a key the provider rejects is **not stored**, and
the box says why. A key that passes is stored encrypted and switched on.
3. The box now shows the verdict — **Verified just now: Anthropic accepted this key.** — and a
locked **API key** field with a redacted fingerprint (`sk-ant-api0…`, `ABSK…bz0=`) so you can tell
which key is in place. The verdict stays: after a reload it reads **Verified 3 minutes ago**, or
**Check failed 2 days ago: …** with the reason.
It takes effect on the next request. There is nothing to change on any engineer's machine — no new
connect command, no config edit.
**Check a key later**
Click **Check key** at any time to re-test the stored key (expired, revoked, model access changed).
The result is remembered, so the box tells the next person what the last check found.
**Rotate a key**
Click **Rotate key**, paste the new key, and click **Check & save**. The new key is tested and then
replaces the old one in place. Rotate on your own schedule the same way you would rotate any
provider key: create the new one, save it here, then revoke the old one at the provider.
**Turn a key off without deleting it**
Use the switch next to the box title. Off means the key stays saved but is not used - the traffic
that key serves uses your other enabled key for the same models, if you have one. Otherwise it runs
on Valar-managed providers with normal charges.
**Remove a key**
Click **Remove key** and confirm. From the next request, the affected models use your other enabled
key for those models, if you have one. Otherwise they return to Valar-managed providers with normal
Valar inference charges and spend caps.
The key is stored encrypted and is never shown again — not in the dashboard, not in the API, not
in a log. Only the redacted fingerprint is ever displayed.
## OpenAI key
An OpenAI API key serves OpenAI models through the Messages API and Codex Responses API. It does not affect your
Claude traffic: that keeps running wherever it ran before - on your own Anthropic or AWS key if you
store one, on Valar-managed providers otherwise.
When you save or check an OpenAI key, Valar asks OpenAI which models the key can reach and lists any
OpenAI model it cannot. That usually means the key's OpenAI **project** has not been granted access
to the model; grant it in the OpenAI console and click **Check key** again. The key is still stored -
it authenticated, and the models it can reach are served on it.
This check lists available models without generating tokens. It does not verify your credit balance
or permission to generate responses. A request can still fail if either is missing.
Any OpenAI key shape works (`sk-`, `sk-proj-`, `sk-svcacct-`). Use one whose project has the spend
limits and rate limits you want for your whole team.
## AWS Bedrock key
A Bedrock API key works from any AWS region. Which AWS endpoint Valar calls with it, and where in
the world the model runs, is set by the [Endpoint and region](#endpoint-and-region) controls in the
key box; the default lets AWS decide.
### Also serve OpenAI models on your Bedrock key
Bedrock supports OpenAI models as well as Claude models; your AWS account must have access to them. The Bedrock box has a switch -
**Also serve OpenAI models on this key** - that extends the key you already stored to that traffic
too. It is **off** by default and stays off until you turn it on, so a key you stored for Claude
keeps serving Claude only, and your OpenAI-model spend does not move onto your AWS bill without you
asking for it.
Turning it on re-checks the key. With it on, AWS bills you for OpenAI traffic served on this key and
Valar charges \$0. With it off, OpenAI traffic uses your enabled OpenAI API key, if present, or
Valar-managed providers with normal charges. If both keys are enabled for OpenAI, requests can use
either of your accounts. The Bedrock check verifies Claude access; it does not verify OpenAI model
access or change that access in AWS.
When you save or check a Bedrock key, Valar tests it against **every Claude model** it serves
through Bedrock, on the endpoint you selected, and the box lists any model the key authenticated
for but cannot use, with the reason. Two kinds of line:
* **Transient** — AWS was overloaded, timed out, or is still enabling the model on your account
(the first use of each model creates a Marketplace subscription, which takes about a minute). The
key is fine; click **Check key** again. If an *Overloaded* line persists for one model while the
others work, your account's on-demand throughput quota for that model is probably zero — new
accounts start there for Opus-class models. Request an increase in the AWS console (Service
Quotas → Bedrock), then check again.
* **Not usable on your AWS account** — the account itself blocks the model. The line says what to
change; the common cases are under [What the key check can tell you](#what-the-key-check-can-tell-you).
### Endpoint and region
AWS offers two endpoints that accept the same Bedrock API key for Claude. The Bedrock key box lets
you pick which one your traffic uses:
| Setting | Options | What it does |
| - | - | - |
| **Endpoint** | **Mantle (default)** or **bedrock-runtime** | Which AWS endpoint Valar calls with your key. |
| **Region** | Disabled on Mantle ("AWS decides routing"); **US** on bedrock-runtime | Where the model runs. Applies to bedrock-runtime only — on Mantle, AWS decides the routing, which may include regions outside the US. More regions are added as Valar verifies them. |
Changing a select does not apply anything by itself — the row reads **Not applied yet** until you
commit it with a button:
* **Key already stored**: click **Save & check**. Valar saves the setting, then re-tests your
stored key on the endpoint you picked. **Cancel** puts the selects back and saves nothing.
* **Adding or rotating a key**: the selects are part of the form and are saved together with the
key when you click **Check & save**. The new key is tested on the endpoint you picked.
**When to use bedrock-runtime + US.** Choose it when your AWS organization blocks global routing,
or requires that your Claude traffic stays in US regions. On Mantle, AWS resolves the model itself
and may serve it from any region; a policy that denies that will fail your Fable 5 requests (and
may let other models quietly leave the US). On bedrock-runtime with **US**, Valar asks for the
model's `us.` inference profile, so the request is served only from US regions. Note that AWS
prices US-region (geographic) inference about 10% higher than global inference — see
[Amazon Bedrock pricing](https://aws.amazon.com/bedrock/pricing/).
**The same key, different permissions.** The two endpoints are gated by different IAM actions —
`bedrock:InvokeModel` and `bedrock:CallWithBearerToken` for bedrock-runtime,
`bedrock-mantle:CreateInference` and `bedrock-mantle:CallWithBearerToken` for Mantle (see AWS:
[API keys → Control who can generate and use API keys](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys.html)
for the two `CallWithBearerToken` actions, and
[Bedrock Mantle → Prerequisites → Permissions](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html)
for `bedrock-mantle:CreateInference` and `bedrock:InvokeModel`) — so a key that passes on one can
fail on the other, and a policy in your AWS organization can allow one and deny the other. That is
why the key check always runs on the endpoint you selected. If it fails after switching, ask your
AWS administrator to allow the actions for that endpoint on the key's IAM user.
**Failover is unchanged.** With both keys, a request that fails on your selected Bedrock endpoint
falls back to your Anthropic key. With a Bedrock key only, it returns a clear error to the harness
instead — it is never served, and never billed, on Valar's account.
### Claude Fable 5 needs an opt-in
Anthropic treats Claude Fable 5 (and Mythos 5) as *covered models*: AWS only serves them if your
account has agreed that prompts and completions may be **shared with Anthropic and kept for up to 30
days** for safety review. Older Claude models do not require this. AWS enforces it through an
account setting called the *data retention mode*; a new account starts on `default`, which means
"not agreed", so Bedrock refuses Fable 5 until you set it to `provider_data_share`.
**AWS stores this setting separately for each endpoint.** Opting in through Mantle's API does
**not** cover bedrock-runtime, and the other way round. Opt in on the endpoint your key is set to;
if you switch endpoints later, opt in again on the new one.
**On Mantle (the default endpoint)** — one API call, made with your Bedrock key:
```bash theme={"system"}
curl -X PUT https://bedrock-mantle.us-east-1.api.aws/v1/data_retention \
-H "x-api-key: $BEDROCK_API_KEY" \
-H "content-type: application/json" \
-d '{"mode":"provider_data_share"}'
```
To limit the sharing to one Bedrock project instead of the whole account, set it on the project
the key belongs to:
```bash theme={"system"}
curl -X POST https://bedrock-mantle.us-east-1.api.aws/v1/organization/projects/ \
-H "x-api-key: $BEDROCK_API_KEY" \
-H "content-type: application/json" \
-d '{"data_retention":{"mode":"provider_data_share"}}'
```
**On bedrock-runtime + US** — the setting lives on the Bedrock control plane, per region. Under
cross-region inference AWS stores retained data in the region that served the request, so set it in
**each** US region the `us.` profile can serve from (`us-east-1`, `us-east-2`, `us-west-2`):
```bash theme={"system"}
for r in us-east-1 us-east-2 us-west-2; do
aws bedrock put-account-data-retention --mode provider_data_share --region "$r"
done
```
Or, without the AWS CLI: `PUT https://bedrock..amazonaws.com/data-retention` with the body
`{"mode":"provider_data_share"}`, once per region, signed with AWS credentials. Both forms are the
same control-plane API — see AWS:
[Data retention → Configuring data retention → Set account-wide data retention → Bedrock Control Plane](https://docs.aws.amazon.com/bedrock/latest/userguide/data-retention.html)
(the `PUT /data-retention` call; the CLI command is its `aws bedrock` surface).
Two things to know about this call:
* A Bedrock API key **cannot** make it. It needs an IAM identity (a user or role) with the
`bedrock:PutAccountDataRetention` permission — typically an administrator signed in to the AWS
account (the same AWS page's "IAM actions reference" maps `PUT /data-retention` to
`bedrock:PutAccountDataRetention` and `GET /data-retention` to `bedrock:GetAccountDataRetention`).
* It can take **up to about an hour** to propagate. Confirm it with
`aws bedrock get-account-data-retention --region ` in each region (AWS: "Check your
current configuration → Bedrock Control Plane"); when all three report `provider_data_share`,
click **Check key**.
Then click **Check key**; the Fable 5 line disappears. Until you opt in, the other Claude models
work on your key and a Fable 5 request on it fails. Details:
[Amazon Bedrock — Data retention](https://docs.aws.amazon.com/bedrock/latest/userguide/data-retention.html).
Claude Fable 5.1, the current Fable fallback, is not on Bedrock yet, so it is served only through an
Anthropic key. A Bedrock-only key cannot serve a Fable-class request that falls back to it; add an
Anthropic key alongside, or pin the Fable slot to Claude Fable 5 in the routing editor.
### What the key check can tell you
Each line in the box is one situation and its action. The common ones:
| The box says | What it means | What to do |
| - | - | - |
| **AWS doesn't recognize this key.** | The key is not a Bedrock API key AWS knows — usually a partial paste, a deleted key, or an expired temporary key. | Copy the whole key again from **Bedrock → API keys**, or create a new long-term key, and save it. |
| **AWS won't let this key use Claude.** | AWS authenticated the key but its IAM user may not invoke Claude on the endpoint you selected, or the Claude models are not enabled for your account. | Ask your AWS administrator to allow the IAM actions for that endpoint (see [Endpoint and region](#endpoint-and-region)) and to enable the Claude models in Bedrock, then click **Check key**. |
| **Fable 5 — your AWS account hasn't opted in to sharing prompts with Anthropic … or your AWS organization may be restricting Bedrock to US regions** (on Mantle) | AWS gives the same answer for two different causes: no opt-in yet, or an organization policy that denies global routing. | If you have not opted in, do so on Mantle as above. If you already have, set **Endpoint** to **bedrock-runtime** and click **Save & check**. |
| **Fable 5 — your AWS account hasn't opted in to sharing prompts with Anthropic for US-region Bedrock** (on bedrock-runtime + US) | The opt-in is missing on the Bedrock control plane in one or more US regions. The Mantle opt-in does not count here. | Run the per-region opt-in above, wait for it to propagate, then click **Check key**. |
| A model line ending **Fix this in your AWS Bedrock account** with AWS's own words, such as the model not existing or not being available | The model is not available to your account on the endpoint and region you selected — it is not enabled there, or AWS is not serving it there right now. | Check the model is enabled for your account in the US regions. For Claude Haiku 4.5, see the [known limitation](#known-limitation-claude-haiku-45-on-bedrock-runtime) below. |
### Known limitation: Claude Haiku 4.5 on bedrock-runtime
AWS intermittently reports Claude Haiku 4.5 (inference profile
`us.anthropic.claude-haiku-4-5-20251001-v1:0`) as unavailable in some US regions on
bedrock-runtime. This is on AWS's side and not something your key or account can fix.
* If you also have an Anthropic key, Haiku requests that fail on Bedrock fall back to it — you
will not notice beyond a line in the key check.
* If your organization uses **only** a Bedrock key on bedrock-runtime + US, Haiku 4.5 requests may
fail until AWS resolves it. Other Claude models are not affected.
**Temporary keys expire.** A 12-hour Bedrock API key (starts with `bedrock-api-key-`), or a
long-term key with an expiry set in AWS, stops your Claude traffic when it lapses — and **Check
key** cannot see an expiry date. Use a long-term key, and rotate it here before it expires. The box
warns when you paste a temporary key, but does not stop you.
## What it costs
| | On your key | On Valar-managed providers |
| - | - | - |
| Claude and OpenAI tokens | Billed by your provider to your account | Included in what Valar charges you |
| Valar inference charge | **\$0** | Valar's per-token rate for the model |
| Tokens metered by Valar | Yes — input, cached, and output | Yes |
Valar still counts every token so the traffic is measurable. It is simply priced at zero, because
your provider bills your account for it.
Your open-weight traffic is unchanged. Models such as GLM-5.2 and Kimi-K3 still run on
Valar and are billed by Valar. A routing policy that mixes open-weight, Claude, and OpenAI
models can produce both provider charges and Valar charges.
## Exactly which requests use your key
On the supported APIs below, requests served by a model for which you have an enabled,
eligible key use that key. This includes Auto routing and capability escalations to those
models. Claude fallback requests on the Messages API also use your eligible Claude key.
Requests served by an open-weight model remain billed by Valar.
BYOK covers these coding requests:
| Request | Customer keys used |
| - | - |
| Claude through the Messages API (`/v1/messages`) | Your enabled Anthropic or AWS Bedrock key |
| OpenAI through the Messages API or Codex Responses API (`/v1/responses`) | Your enabled OpenAI API key or a Bedrock key with **Also serve OpenAI models on this key** enabled |
| Chat Completions API (`/v1/chat/completions`), including Cursor | Stored provider keys do not apply; normal Valar charges apply |
Claude requests made through Cursor or Codex do not use your stored provider keys. The OpenAI
Responses support above does not extend Claude BYOK to those tools.
## Where this traffic shows up
Requests served on your key appear in **BYOK usage** on the ValarCode **Metrics** tab once
the selected time window contains own-key requests. Valar records the tokens and charges \$0
for inference. The regular usage and savings panels exclude this traffic.
For the actual cost, use your provider's usage dashboard: Anthropic, OpenAI, or AWS Cost
Explorer for Bedrock. That provider bills your account.
## Next steps
Decide which requests reach Claude in the first place.
See what the panels measure, and why own-key traffic sits outside them.