Vault secrets for interns

The Vault API stores credentials that your interns send to third-party APIs. Each secret is bound to an exact list of hostnames, and the intern runtime releases the value only to requests bound for one of those hostnames. Your code never handles the plaintext after the store call, and the API never returns it. All routes live under https://openrouter.ai/api/v1/vault and take an API key as a bearer token. The full route reference is in the Vault API reference. Every vault route, including GET, requires access to the Intern API programme. Outside the programme every route answers 404, the same response the dashboard gives when interns are not enabled. Writes are enabled separately inside the programme, see Writes are enabled per account.

Scope is selected by the API key

A secret belongs to either a workspace or one intern inside that workspace.

Workspace secrets live at /api/v1/vault/secrets. They are the pool you copy from when you give an intern a credential.
Intern secrets live at /api/v1/vault/interns/{internId}/secrets. They are the secrets that intern can use.

The workspace is always the active workspace of the API key that makes the request. You cannot pass a workspace ID, there is no default workspace, and a key never falls back to another scope. An intern route additionally requires internId to be an intern in that same workspace, otherwise the request fails with 404. Vault routes are served on the global hostname only. A request to a regional hostname such as eu.openrouter.ai is refused with 403.

Responses carry metadata only

Every successful response describes secrets without their values.

{
  "name": "github_token",
  "hosts": ["api.github.com"],
  "fingerprint": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "created_at": "2026-09-15T17:44:00.000Z"
}

Field	Meaning
`name`	The secret name you chose.
`hosts`	The exact hostnames the secret may be sent to. `null` marks a secret stored before host binding existed. Store it again with `hosts` to bind it.
`fingerprint`	A keyed SHA-256 digest of the value. Two secrets in the same scope with equal fingerprints hold equal values. The key differs per scope, so a workspace secret and its intern copy have different fingerprints. `null` for a secret stored before fingerprints were recorded.
`created_at`	When the secret was first stored, in ISO 8601 format.

Store a secret

PUT the value and its hosts to the secret’s name. Storing a name that already exists replaces the value and hosts.

curl -X PUT https://openrouter.ai/api/v1/vault/secrets/github_token \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "ghp_exampleToken",
    "hosts": ["api.github.com"]
  }'

{
  "data": {
    "name": "github_token",
    "hosts": ["api.github.com"],
    "fingerprint": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "created_at": "2026-09-15T17:44:00.000Z"
  }
}

Use PUT /api/v1/vault/interns/{internId}/secrets/{name} with the same body to store a secret for one intern directly. Names are 1 to 255 characters, start with a lowercase letter, and contain only lowercase letters, digits, and single underscores. A name cannot end with an underscore or contain __. github_token and db2_password are valid, GitHub-Token, _token, and a__b are not. Values are 1 to 65,536 characters. The whole request body must stay under 425,000 bytes or the request fails with 413. Hosts must be present with 1 to 100 entries. The rules are in Host rules. Unknown fields in the body fail the request with 400.

List secrets

curl "https://openrouter.ai/api/v1/vault/secrets?limit=50&offset=0" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

{
  "data": [
    {
      "name": "github_token",
      "hosts": ["api.github.com"],
      "fingerprint": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "created_at": "2026-09-15T17:44:00.000Z"
    },
    {
      "name": "legacy_token",
      "hosts": null,
      "fingerprint": null,
      "created_at": "2026-08-01T09:00:00.000Z"
    }
  ],
  "has_more": false
}

Results are sorted by name. limit is 1 to 100 and defaults to 100. offset is 0 to 10,000 and defaults to 0. has_more is true when another page exists after this one, so keep adding limit to offset until it is false. A value outside those bounds fails with 400. Use GET /api/v1/vault/interns/{internId}/secrets with the same parameters to list one intern’s secrets.

Copy workspace secrets to an intern

Copying is how you hand a workspace credential to an intern without sending the value again. Each copy keeps the source value and hosts, and replaces any intern secret with the same name.

curl -X POST https://openrouter.ai/api/v1/vault/interns/7c9e6679-7425-40de-944b-e07fc1f90ae7/secrets/copy \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "names": ["github_token", "openai_api_key"] }'

{
  "data": [
    {
      "name": "github_token",
      "hosts": ["api.github.com"],
      "fingerprint": "sha256:3e23e8160039594a33894f6564e1b1348bbd7a0088d42c4acb73eeaed59c009d",
      "created_at": "2026-09-15T17:44:00.000Z"
    },
    {
      "name": "openai_api_key",
      "hosts": ["api.openai.com"],
      "fingerprint": "sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
      "created_at": "2026-09-15T17:44:00.000Z"
    }
  ]
}

names holds 1 to 100 distinct workspace secret names. A repeated name fails with 400. Every name must exist in the workspace, otherwise the request fails with 404 and nothing is copied. Conflicts. The request fails with 409 and the message Vault request conflicts with existing secrets when a named workspace secret has hosts: null, or when the intern is in the middle of a transfer to another workspace. Nothing is copied. For a null-host secret, store it again with hosts and retry. For a transfer, retry once the transfer has finished.

Delete a secret

curl -X DELETE https://openrouter.ai/api/v1/vault/secrets/github_token \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

A successful delete returns 204 with no body. Deleting a name that does not exist in that scope returns 404. Deleting a workspace secret does not touch copies already made to interns, and deleting an intern’s copy does not touch the workspace secret. Use DELETE /api/v1/vault/interns/{internId}/secrets/{name} to remove one intern’s secret.

Host rules

A host is an exact DNS hostname. The API normalizes each entry and then checks it.

Hostnames are lowercased and a trailing dot is removed, so API.Example.com. is stored as api.example.com.
Schemes, ports, paths, wildcards, and empty strings are rejected. https://api.example.com, api.example.com:443, api.example.com/v1, and *.example.com all fail with 400.
Each label is 1 to 63 characters of letters, digits, and hyphens, and cannot start or end with a hyphen. The whole hostname is at most 253 characters.
An array holds 1 to 100 hosts. Entries that are equal after normalization are collapsed into one.

Matching at release time is exact. A secret bound to api.example.com is never released to example.com, www.api.example.com, or any other hostname. Bind every hostname the intern needs to call.

Errors

Errors use the standard OpenRouter shape.

{
  "error": {
    "code": 409,
    "message": "Vault request conflicts with existing secrets"
  }
}

Status	When
`400`	The name, body, hosts, or query parameters failed validation.
`401`	The API key is missing or invalid.
`403`	The key’s workspace cannot be used for vault requests, or the request used a regional hostname.
`404`	The key is outside the Intern API programme, the intern is not in the key’s workspace, or the named secret does not exist in that scope.
`408`	The request or its body took too long to arrive.
`409`	Copy conflict, or the intern is being transferred. See Copy workspace secrets to an intern.
`413`	The request body exceeds 425,000 bytes.
`429`	Too many vault requests. Retry with backoff.
`500`	An internal error.
`502`	The vault service returned an unexpected response.
`503`	Vault writes are not enabled for your account, or the vault service is unavailable.
`504`	The vault service did not respond in time.

Writes are enabled per account

Inside the Intern API programme, writes (PUT, DELETE, and POST) are enabled per account during the Ori rollout. Until they are enabled for yours, every write returns 503 with the message Vault writes are not enabled, while GET requests keep working for accounts in the programme.

Overview

Models & Routing

Tool Calling

Features

Ori

Privacy

Best Practices

Community

Vault secrets for interns

Scope is selected by the API key

Responses carry metadata only

Store a secret

List secrets

Copy workspace secrets to an intern

Delete a secret

Host rules

Errors

Writes are enabled per account

​Scope is selected by the API key

​Responses carry metadata only

​Store a secret

​List secrets

​Copy workspace secrets to an intern

​Delete a secret

​Host rules

​Errors

​Writes are enabled per account

Scope is selected by the API key

Responses carry metadata only

Store a secret

List secrets

Copy workspace secrets to an intern

Delete a secret

Host rules

Errors

Writes are enabled per account