---
title: "Store an intern secret"
method: PUT
path: "/vault/interns/{internId}/secrets/{name}"
tags: ["Vault"]
---

# Store an intern secret

`PUT /vault/interns/{internId}/secrets/{name}`

Creates or replaces a secret stored for one intern. The value is encrypted at rest and released only to the exact hostnames in `hosts`. The response carries metadata only. Writes return 503 while vault writes are disabled for the caller. The scope is selected by the API key: workspace routes act on the key's active workspace and intern routes act on one intern inside that workspace. There is no default workspace and no fallback to another scope. Every vault route, including reads, requires access to the Intern API programme and returns 404 outside it. Requests on regional hostnames such as `eu.openrouter.ai` are refused. [API key](/docs/api-reference/authentication) required.

## Path parameters

- `internId` string, uuid, required — UUID of an intern in the workspace selected by the API key.
- `name` string, required — Secret name. Lowercase letters, digits and single underscores, starting with a letter and not ending with an underscore, 1 to 255 characters.

## Request body

- VaultSecretWriteRequest — Secret value and the exact hostnames it may be released to.
  - `hosts` string[], required — Exact DNS hostnames the secret may be sent to, 1 to 100 entries. Each entry is lowercased and a trailing dot is removed, so `API.Example.com.` is stored as `api.example.com`. Schemes, ports, paths, wildcards and empty values are rejected. Duplicates after normalization are collapsed. Matching is exact: a secret bound to `api.example.com` is never released to `example.com` or any other hostname.
  - `value` string, required — Secret value, 1 to 65536 characters. It is encrypted at rest and never returned.

## Response `200`

Metadata for the stored secret.

- VaultSecretResponse — Metadata for the stored secret.
  - `data` VaultSecret, required — Metadata for one stored secret. The secret value is never returned. `fingerprint` is an HMAC-SHA-256 of the value keyed with that vault's own data key, so it is comparable only within one vault: equal fingerprints in one vault mean equal values, and rewriting the same value keeps its fingerprint. The same value stored in two vaults (for example a workspace secret and its intern copy) carries different fingerprints, so comparing fingerprints across vaults cannot show that a copy matches or that a rotation propagated. `hosts` and `fingerprint` are `null` only for legacy rows written before host binding was required; storing the secret again assigns hosts.
    - `created_at` string, date-time, required
    - `fingerprint` string, nullable, required
    - `hosts` string[], nullable, required
    - `name` string, required

## Other responses

- `400` — Bad Request - The secret name, path, query or JSON body failed validation. The vault returns 400 for a malformed request as well.
- `401` — Unauthorized - Missing or unknown API key. Provisioning keys cannot call vault routes.
- `403` — Forbidden - The key has no usable workspace scope, or the request arrived on a regional hostname.
- `404` — Not Found - The intern is not in the selected workspace, the secret does not exist in the selected scope, or the caller is outside the intern programme.
- `408` — Request Timeout - The route deadline passed before the request completed, or the request body stopped arriving.
- `409` — Conflict - The intern is being transferred to another workspace and its vault has not moved yet. Retry once the transfer finishes.
- `413` — Payload Too Large - The JSON body exceeds 425000 bytes.
- `429` — Too Many Requests - The vault rate limit was reached.
- `500` — Internal Server Error - Scope lookup failed.
- `502` — Bad Gateway - The vault could not be reached or returned an unexpected response.
- `503` — Service Unavailable - Vault writes are disabled for the caller, or the vault is not configured.
- `504` — Gateway Timeout - The vault did not answer in time.

## Changes

- **2026-09-16** `1e05e5f6495c` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openrouterteam/apis/openrouter-api/changes/vault/interns/:internId/secrets/:name/put.md)

---

[API](https://skmtc.dev/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.dev/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openrouterteam/apis/openrouter-api/revisions/2b75a8109d8f?raw)