API reference

Secrets

The organization's session secrets, their bound hosts and who may use them; a value is never read back.

GET/v1/dev/secrets

List secrets

The organisation's session secrets, their bound hosts and who may use them; never a value.

A session sends its placeholder (the variable CIRESK_SECRET_<NAME>, ciresk_placeholder_<name>.<nonce>) in the secret's header; the worker's egress proxy attaches the value on a TLS connection to one of the secret's hosts, outside the pod. Values are write-only: no capability returns one. repos, templates and agent_sessions select sessions; they do not authorise: every member who may start a session in the organisation can use a secret through the proxy.

Permission: dev:secrets.read

Response200 OK

dataarray of objectsRequired
data[].agent_sessionsbooleanRequired: a session whose requester is not a user principal (an agent, a service, a key) gets the secret only when true
data[].headerstringRequired: the request header the value goes in: authorization (Bearer, any scheme, or Basic's user or password) or one custom header name
data[].hostsarray of stringsRequired: exact names the value is attached for, host or host:port (443 when left out); no wildcard, no ip literal
data[].namestringRequired: not starting with model_ (the model front's placeholders)
data[].purposestring: proxy: the session's egress proxy puts the value in header on requests to hosts; git: the worker's push credential for the forge on hosts (a token for https, an openssh private key for ssh), never handed to the proxy, so no placeholder in the pod stands for it. a change of purpose widens the secretOne of proxy, git
data[].reposarray of stringsRequired: * or normalised repositories (github.com/acme/app) whose sessions get the secret; a selector, not a boundary
data[].templatesarray of stringsRequired: template names whose sessions get the secret; empty for any
data[].updated_atstring (date-time)Required
data[].updated_bystringRequired
data[].versionintegerRequired

Errors

401an error
403an error

curl "$CIRESK_API/v1/dev/secrets" \
  -H "Authorization: Bearer $CIRESK_KEY"

PUT/v1/dev/secrets/{name}

Set a secret

Create or replace a session secret; the value is stored through the vault port and never read back.

An org admin with dev:secrets.write. value is required to create, and again whenever hosts or header change or repos, templates or agent_sessions widen (422 value_required); a pure narrowing may leave it out and keeps the stored value. A change reaches a running session within 5 minutes. Audited without the value (dev.secrets.set: the name, the metadata diff, value_changed).

Permission: dev:secrets.write

Parameters

Name	Type	Required	Description
`name`path	string	Required	the name a session's placeholder carries: ciresk_placeholder_<name>

Request body

agent_sessionsboolean
headerstring
hostsarray of stringsRequired
purposestring: proxy: the session's egress proxy puts the value in header on requests to hosts; git: the worker's push credential for the forge on hosts (a token for https, an openssh private key for ssh), never handed to the proxy, so no placeholder in the pod stands for it. a change of purpose widens the secretOne of proxy, git
reposarray of stringsRequired: * or a repository as dev.templates.promote takes it
templatesarray of strings
valuestring: required to create and to widen; absent keeps the stored value on a pure narrowing

Response200 OK

agent_sessionsbooleanRequired: a session whose requester is not a user principal (an agent, a service, a key) gets the secret only when true
headerstringRequired: the request header the value goes in: authorization (Bearer, any scheme, or Basic's user or password) or one custom header name
hostsarray of stringsRequired: exact names the value is attached for, host or host:port (443 when left out); no wildcard, no ip literal
namestringRequired: not starting with model_ (the model front's placeholders)
purposestring: proxy: the session's egress proxy puts the value in header on requests to hosts; git: the worker's push credential for the forge on hosts (a token for https, an openssh private key for ssh), never handed to the proxy, so no placeholder in the pod stands for it. a change of purpose widens the secretOne of proxy, git
reposarray of stringsRequired: * or normalised repositories (github.com/acme/app) whose sessions get the secret; a selector, not a boundary
templatesarray of stringsRequired: template names whose sessions get the secret; empty for any
updated_atstring (date-time)Required
updated_bystringRequired
versionintegerRequired

Errors

401an error
403an error
422secret_invalid (a name, host, header, repository or template off its rule, a name starting ciresk_ (reserved, amendment of 2026-10-25), a host a model or tool vendor, a wildcard or an ip literal, a value under 16 or over 8192 bytes or with a control character); value_required (a create, or a change that moves hosts or header or widens repos, templates or agent_sessions, without a value)
503secrets_unavailable (the installation has no DEV_SECRETS_VAULT)

curl -X PUT "$CIRESK_API/v1/dev/secrets/target/dist/platform-api.tar.zst" \
  -H "Authorization: Bearer $CIRESK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_sessions": true,
    "header": "acme/platform",
    "hosts": [
      "registry.npmjs.org"
    ],
    "purpose": "proxy",
    "repos": [
      "acme/platform"
    ],
    "templates": [
      "platform"
    ],
    "value": "acme/platform"
  }'

DELETE/v1/dev/secrets/{name}

Delete a secret

Delete a session secret and its value.

Permission: dev:secrets.write

Parameters

Name	Type	Required	Description
`name`path	string	Required	the name a session's placeholder carries: ciresk_placeholder_<name>

Response204 No Content

deleted

Errors

401an error
403an error
404secret_not_found
503secrets_unavailable

curl -X DELETE "$CIRESK_API/v1/dev/secrets/target/dist/platform-api.tar.zst" \
  -H "Authorization: Bearer $CIRESK_KEY"