Rotate or re-bind a secret

Rotate the value and/or change how it is delivered. A rotation reaches NEW RUNS ONLY: a session already running holds the old value — materialized in its box’s environment, or inside an egress policy that cannot be read back — and there is no safe way to replace it mid-run.

PATCH /projects/{projectId}/secrets/{secretId}

Rotate or re-bind a secret

cURL

curl --request PATCH \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/secrets/{secretId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "value": "<string>",
  "description": "<string>",
  "brokerHosts": [
    "<string>"
  ],
  "brokerHeader": "<string>",
  "brokerTemplate": "<string>"
}
'

200

Example

{ "id": "<string>", "projectId": "<string>", "name": "<string>", "description": "<string>", "delivery": "brokered", "sharing": "user", "lastDeliveredAt": 123, "createdAt": 123, "updatedAt": 123, "createdByUserId": "<string>", "updatedByUserId": "<string>", "brokerHosts": [ "<string>" ], "brokerHeader": "<string>", "brokerTemplate": "<string>", "ownerUserId": "<string>" }

Authorizations

Authorization · string · header · required

MCPJam API key (sk_…). Create one at Settings → API keys. Guest sessions cannot use the API, and API keys cannot manage other API keys.

Path Parameters

projectId · string · required

ID of the hosted project that contains the server.

secretId · string · required

Secret ID, as returned by the project's secret list.

Body

application/json

The fields to change.

At least one field. name and sharing are absent because both are IMMUTABLE: renaming would break the workflows referencing the environment variable, and re-sharing would change who has already been handed the value. Delete and recreate for either. A rotation reaches NEW RUNS ONLY — a session already running holds the old value and cannot be reached.

value · string

The new credential. Same exposure as on create: it travels in this body.

Maximum string length: 65536

description · string | null

null clears it; omit to leave it unchanged.

Maximum string length: 500

delivery · enum<string>

Switching to brokered requires the host binding in the same call; switching to materialized clears it.

Available options: brokered, materialized

brokerHosts · string[]

Required for brokered, forbidden for materialized. Exact hostnames — no scheme, no port, no wildcard: the proxy matches a host, and a URL installs a rule that silently never fires.

Required array length: 1 - 10 elements

brokerHeader · string

Required for brokered, forbidden for materialized. e.g. Authorization.

Maximum string length: 64

brokerTemplate · string

Required for brokered, forbidden for materialized. The header value with {} where the secret goes, e.g. Bearer {}. A template without {} is rejected: it installs a constant header that never carries the credential.

Maximum string length: 256

Response

200

application/json

The updated secret, as metadata.

A project credential — METADATA ONLY, always. There is no value field on this schema and no route that returns one: a secret is written and delivered into a run, never read back.

id · string · required

projectId · string · required

name · string · required

The environment-variable name (^[A-Z_][A-Z0-9_]*$). This IS the secret's identity: what a materialized delivery exports, what a workflow references, and what stays stable across a rotation. Immutable.

description · string | null · required

delivery · enum<string> · required

brokered — the sandbox's egress proxy injects the value as a request header OUTSIDE the VM, so the box never holds it. Prevents EXTRACTION, not USE: any process in the box can call the bound host while the policy is live, and it works for HTTPS APIs only (domain rules bind on ports 80/443). materialized — a real environment variable inside the box, which is the only thing a CLI can read; EXTRACTABLE BY DESIGN.

Available options: brokered, materialized

sharing · enum<string> · required

project — admin-managed, delivered to every member's sessions. user — personal, delivered ONLY in sessions its owner starts and silently absent from anyone else's run of the same environment. Immutable.

Available options: user, project

lastDeliveredAt · integer | null · required

When this secret was last HANDED TO a run — not when it was last used. Brokered use is unobservable by construction (the proxy injects the header; the request is never seen here), so used would be a number nobody can honestly produce. null means nothing has been recorded, which is not the same as never delivered.

createdAt · integer · required

updatedAt · integer · required

createdByUserId · string · required

updatedByUserId · string · required

brokerHosts · string[]

Brokered only: the exact hostnames the header is injected on.

brokerHeader · string

Brokered only: the header name.

brokerTemplate · string

Brokered only: the header value, with {} where the secret goes.

ownerUserId · string

Personal secrets only. Project-shared rows have no owner.