Automate coding key provisioning

Private Preview Organization admins can give an internal provisioning service an OAuth credential for managing ValarCode keys. The credential is limited to the organization that created it and can manage only keys created through this automation flow.

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.

You can create additional client secrets for rotation. Deploy the new secret before revoking the old one.

Provision a key with Python

Install Requests:

python -m pip install requests

Provide the credential through your secret manager or environment. Do not commit the client secret.

export VALAR_M2M_CLIENT_ID="client_..."
export VALAR_M2M_CLIENT_SECRET="..."
export VALAR_M2M_TOKEN_ENDPOINT="https://signin.valarhq.ai/oauth2/token"
export VALAR_ENGINEER_EMAIL="[email protected]"

# Optional: copy the routing policy from an existing coding key.
export VALAR_ROUTING_SOURCE_KEY_ID="key_..."

To find the source ID, open ValarCode → Setup, select the configured key under Model routing, and copy the Key ID for the automation API shown below the selector. The 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:

import os

import requests

API_BASE_URL = os.getenv("VALAR_API_BASE_URL", "https://api.valarhq.ai")
CLIENT_ID = os.environ["VALAR_M2M_CLIENT_ID"]
CLIENT_SECRET = os.environ["VALAR_M2M_CLIENT_SECRET"]
TOKEN_ENDPOINT = os.environ["VALAR_M2M_TOKEN_ENDPOINT"]
ENGINEER_EMAIL = os.environ["VALAR_ENGINEER_EMAIL"]

token_response = requests.post(
    TOKEN_ENDPOINT,
    data={
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
    timeout=15,
)
token_response.raise_for_status()
access_token = token_response.json()["access_token"]

headers = {"Authorization": f"Bearer {access_token}"}
workspace_id = os.getenv("VALAR_WORKSPACE_ID")
if workspace_id:
    headers["X-Workspace-Id"] = workspace_id

payload = {"email": ENGINEER_EMAIL}
source_key_id = os.getenv("VALAR_ROUTING_SOURCE_KEY_ID")
if source_key_id:
    payload["routing_policy"] = {"source_key_id": source_key_id}

response = requests.post(
    f"{API_BASE_URL}/v1/organization/keys",
    headers=headers,
    json=payload,
    timeout=15,
)
response.raise_for_status()
created = response.json()

print(f"Created {created['id']} for {created['email']}")
print(f"ValarCode key (shown once): {created['token']}")

The routing source key must belong to the selected workspace and already have a routing policy. If you omit 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 example template: 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 gateway serves the new routing within about a minute.

response = requests.put(
    f"{API_BASE_URL}/v1/organization/keys",
    headers=headers,
    params={"email": ENGINEER_EMAIL},
    json={"routing_policy": {"source_key_id": os.environ["VALAR_FRONTIER_TEMPLATE_KEY_ID"]}},
    timeout=15,
)
response.raise_for_status()

The response is the key record without its token, including 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. 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. The gateway refreshes routing about every 30 seconds per instance, so for up to half a minute after a change requests can still 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 (claude-opus-5-5, claude-opus-5, claude-sonnet-5-5, claude-sonnet-5, claude-haiku-4-5, claude-fable-5-1). 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 same headers from the example above:

response = requests.get(
    f"{API_BASE_URL}/v1/organization/keys",
    headers=headers,
    params={"email": ENGINEER_EMAIL},  # Omit params to list every automation-managed key.
    timeout=15,
)
response.raise_for_status()

for key in response.json():
    routing = key.get("routing")  # Absent until a routing policy has been saved for the key.
    print(key["id"], key["email"], "revoked" if key["revoked"] else "active",
          routing and f"routing v{routing['version']} since {routing['changed_at']}")

Add 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:

response = requests.get(
    f"{API_BASE_URL}/v1/organization/keys",
    headers=headers,
    params={"include": "templates"},
    timeout=15,
)
response.raise_for_status()

templates = {k["name"]: k["id"] for k in response.json() if k["provisioning_source"] == "dashboard"}
frontier_template_id = templates["template: frontier_and_open"]

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

The id 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:

usage = requests.get(
    f"{API_BASE_URL}/v1/usage/coding/models",
    headers=headers,
    params={"key_id": created["id"], "start": "2026-08-01", "end": "2026-08-31"},
    timeout=15,
)
usage.raise_for_status()
for model in usage.json()["models"]:
    print(model["served_model"], model["input_tokens"], model["output_tokens"], model["spend"] / 100)

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.

response = requests.patch(
    f"{API_BASE_URL}/v1/organization/keys",
    headers=headers,
    params={"email": ENGINEER_EMAIL},
    json={"enabled": False},   # True to restore
    timeout=15,
)
response.raise_for_status()
print(response.json()["enabled"])  # False

The response is the key record without its token. Every list row also carries 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, and the dashboard shows the key as Disabled in both key lists. 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:

response = requests.delete(
    f"{API_BASE_URL}/v1/organization/keys",
    headers=headers,
    params={"email": ENGINEER_EMAIL},
    timeout=15,
)
response.raise_for_status()

Create requests return 409 Conflict when that email already has a live automation-managed key in the selected workspace. Revoke the existing key before creating its replacement.

Getting started

Build agents

Run in production

ValarCode

Platform

Automate coding key provisioning

Create a credential

Provision a key with Python

Update an engineer’s routing

List provisioned keys

Read a key’s usage

Suspend and restore an engineer’s key

Revoke an engineer’s key

​Create a credential

​Provision a key with Python

​Update an engineer’s routing

​List provisioned keys

​Read a key’s usage

​Suspend and restore an engineer’s key

​Revoke an engineer’s key

Create a credential

Provision a key with Python

Update an engineer’s routing

List provisioned keys

Read a key’s usage

Suspend and restore an engineer’s key

Revoke an engineer’s key