Client secrets and generated ValarCode keys stay valid until you revoke them. OAuth access tokens
expire after one hour; request another token with the same client credentials when needed.
Create a credential
- Open Settings → ValarCode settings → Automation credentials in the Valar dashboard.
- Click Create credential.
- Store the client secret immediately. It is shown only once.
- Copy the client ID and token endpoint shown beside it.
Provision a key with Python
Install Requests:vlrcode_...
value is only the key’s display prefix and cannot be used as source_key_id.
Exchange the credential for an access token, then create the engineer’s key:
VALAR_WORKSPACE_ID, Valar uses the organization’s default workspace.
Store the returned token immediately. Later list calls return the key ID, prefix, state, and
creation time, but never the full key again.
Update an engineer’s routing
Keep one coding key per routing policy as a template, for exampletemplate: open_weights on Auto
routing and template: frontier_and_open with a manual mapping that includes Claude models, and copy a template onto an engineer’s
live key whenever their policy changes. The engineer keeps the same key and nothing is
redistributed; the new routing applies within about a minute.
routing.version and
routing.changed_at for the routing it just wrote. Record the version: a later list showing a higher
version means the routing was changed again, for example by hand in the dashboard. 404 Not Found
means the email has no live automation-managed key in the selected workspace.
The request is idempotent: repeating it with the same template returns 200 OK and changes nothing.
It honors X-Workspace-Id like the other key endpoints, and the template must live in the same
workspace as the engineer’s key.
A copy carries every per-key setting, not only the model mapping: the template’s headroom
compaction and its served-model switch (served_model_text, below) land on the engineer’s key too.
Copies are snapshots. Editing a template later does not move the engineers already on it; send the
same request again to roll the change out. A change applies within about a minute; until then,
requests can see either policy. Every copy
appears in the routing change history under Model routing → Change history with the template’s
name as the reason and “Automation” as the actor. To move the engineer back, copy the Auto
template the same way.
A manual mapping applies to requests that name a Claude model (any claude-* id). A request for the Auto model id (valar-auto) is always
served by Auto routing, whatever the key’s mapping, because that id means “let Valar pick”. To move
an engineer onto a manual mapping, their coding tool must be set to a Claude model, not to Auto.
List provisioned keys
Use the sameheaders from the example above:
include=templates to also list the workspace’s live console-made keys, so your automation can
resolve a template by name instead of storing its id:
enabled and served_model_text, the two per-key switches described below.
Template rows carry name, id, prefix, and routing, never a token. Key ids never change:
updating a key’s routing, from the API or the dashboard, writes a new routing version under the same
id. Only revoking and recreating a key produces a new id.
Read a key’s usage
Theid of a provisioned key is the key_id the ValarCode analytics
endpoints report on and filter by. Those endpoints accept
the same automation credential (the /v1/usage/coding/* routes only; the organization-wide
billing endpoints still need a Valar API key), so the provisioning service can read cost, input
and output tokens, and the served-model mix per engineer with the headers it already has:
Name the serving model per key
When the organization’s Show serving model name in the response body switch is on (Settings, ValarCode), every coding key adds a[served by auto-<strategy>: <model>] line under the answers Auto routing
picked. A key can opt out on its own with the same PATCH the suspend switch uses:
served_model_text and enabled may travel in one request; a body naming neither is 400.
Turning the line off is always accepted. Turning it on while the organization’s switch is off
returns 409 Conflict with code served_model_text_off, because the key would still carry no
line; turn the organization switch on first. The field is absent from rows, and the switch
answers 403 with code served_model_text_key_unavailable, for an organization the per-key
switch has not been released to. A routing copy (routing_policy.source_key_id) sets the switch
to the template’s value.
Suspend and restore an engineer’s key
Disabling a key is the reversible alternative to revoking it. The key keeps its id, its routing, and the token the engineer already has; it just refuses every request until you enable it again. Use it for leave, an offboarding hold, or a spend investigation, where revoke-and-remint would force a new token onto the engineer’s machine.enabled, so a
periodic reconciliation can tell suspended engineers from active ones without keeping state of
its own. 404 Not Found means the email has no live automation-managed key in the selected
workspace. The request is idempotent: disabling a disabled key, or enabling an enabled one,
returns 200 OK and changes nothing.
While a key is disabled, the engineer’s coding tool receives 403 Forbidden with the message
this API key is disabled — ask your organization admin to re-enable it, not the 401 an
unknown key gets, so they know who to ask. The gateway checks the switch on every request; there
is no propagation delay. Usage recorded before the suspension stays attributed to the key. The
dashboard’s API Keys page lists automation keys with an automation chip and the engineer’s
email, and reads enabled from this API rather than showing a suspension status of its own.
A revoked key cannot be disabled or re-enabled: revocation is permanent, and a PATCH on an
email whose only key is revoked returns 404.
Revoke an engineer’s key
Revocation is explicit and immediate:409 Conflict when that email already has a live automation-managed key in
the selected workspace. Revoke the existing key before creating its replacement.