Secret API reference
A value a machine uses, sealed at rest and never answered. Hidden (the default): the machine sees a placeholder, and the egress proxy puts the value in its place, only on HTTPS to the secret's hosts. Visible: the machine holds the value, in its environment variable and in /run/secrets/
Base URL: https://api.withruntime.com. Authentication, idempotency and errors work the same way for every product.
Its states: active, deleted.
Endpoints#
| Method | Path | Description |
|---|---|---|
GET |
/v2/secrets |
List secrets |
GET |
/v2/secrets/{name} |
Get a secret |
PUT |
/v2/secrets/{name} |
set |
DELETE |
/v2/secrets/{name} |
Delete a secret |
List secrets#
GET /v2/secrets
Lists the organization's secrets by name, without their values.
Its action, for a key's grant: secrets:list.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
cursor |
string | No | Where the page starts: a page's next. |
limit |
integer | No | The most items the page holds. At least 1. At most 200. Default: 50. |
Returns a page: items, each a Secret, and next, where the next page starts, none on the last.
In v1: GET /v1/egress-secrets.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/secrets" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.secrets.list();Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.secrets.list()rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.secrets.listTerminalruntime secrets listGet a secret#
GET /v2/secrets/{name}
Returns a secret, without its value.
Its action, for a key's grant: secrets:get.
Path: name.
Returns a Secret.
In v1: GET /v1/egress-secrets/{name}.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/secrets/example" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.secrets.get("example");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.secrets.get("example")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.secrets.get("example")Terminalruntime secrets get exampleset#
PUT /v2/secrets/{name}
Stores or replaces a secret with its value, or changes one without it. Replacing it keeps its placeholder and raises its version; machines' new requests carry the new value within a second, and a visible secret's file holds it within a second. A running machine's processes keep the environment they started with; new commands get the new one. Asked again with the same Idempotency-Key and body, it returns the secret as that request left it. A deleted secret's name stored again is a new secret with a new placeholder, and so is a visible secret stored hidden. Without its value, it changes only the hosts, rules (policies.rules) and scope it names and keeps every other setting: hosts and rules only narrow, refused 400 when wider, since widening needs the value; a visible secret's scope only narrows, since its machines hold its value, and its file is removed within a second from each machine the scope leaves out. A secret not stored yet needs its value (404).
Its action, for a key's grant: secrets:write.
Path: name.
Body: a SecretSet.
Returns a Secret.
In v1: PUT /v1/egress-secrets/{name}.
Examples:
Terminalcurl -X PUT "https://api.withruntime.com/v2/secrets/example" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{}'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.secrets.set("example");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.secrets.set("example")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.secrets.set("example")Terminalruntime secrets set exampleDelete a secret#
DELETE /v2/secrets/{name}
Deletes a secret and its value: no request carries it from then on, open connections' included, and a visible secret's file is removed from every machine within a second. Deleted again, it returns the same deleted secret.
Its action, for a key's grant: secrets:delete.
Path: name.
Returns a Secret.
In v1: DELETE /v1/egress-secrets/{name}.
Examples:
Terminalcurl -X DELETE "https://api.withruntime.com/v2/secrets/example" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.secrets.delete("example");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.secrets.delete("example")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.secrets.delete("example")Terminalruntime secrets delete exampleObjects#
SecretScope
Which machines may use a secret.
| Field | Type | Required | Description |
|---|---|---|---|
labelsAny |
list of object of strings | Yes | Machines with every label of any one of these sets. |
SecretRule
Which requests to a secret's hosts may carry it.
| Field | Type | Required | Description |
|---|---|---|---|
methods |
list of string | No | Only these methods (POST); every method when omitted. |
paths |
list of string | Yes | Only these paths: exact (/v1/chat/completions), or a prefix ending in /*. |
SecretGit
What a git push carrying a secret may update.
| Field | Type | Required | Description |
|---|---|---|---|
push |
list of string | Yes | The branches a push may update: 1 to 16 patterns of 12 to 256 characters, refs/heads/ then a branch name, * only at the end, and {label.<key>} for the machine's own label right below a fixed first segment (refs/heads/task/{label.task}). A tag, a delete or any other ref is refused, and so is every API write that moves a ref. Opening or editing a pull request, reviewing it, and commenting on a pull request or an issue go under any rule that allows the path. Any other API write goes only when a rule names its exact path, with no *. A secret with no rules makes no API write. |
SecretGraphql
The GraphQL mutations a request carrying a secret may make.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | No | The GraphQL endpoint's path; /graphql when omitted. |
mutations |
list of string | Yes | Only these mutations, by name (at most 64); a request making any other is refused. |
SecretApi
What API calls carrying a secret may do.
| Field | Type | Required | Description |
|---|---|---|---|
graphql |
SecretGraphql | No | Its GraphQL mutations. |
SecretPolicies
How a secret may be used, beyond its hosts: a request carries it only when every policy it holds allows it.
| Field | Type | Required | Description |
|---|---|---|---|
rules |
list of SecretRule | No | Only requests one of these rules allows carry it; every request to its hosts when omitted. A set with its value and without rules removes them; one without its value keeps them, or narrows them to these. |
git |
SecretGit | No | Its git pushes' branches. Kept when a set leaves it out; only a set with the value changes it. |
api |
SecretApi | No | Its API calls' limits. Kept when a set leaves it out; only a set with the value changes it. |
SecretSettings
A secret's settings: what it keeps beside its sealed value.
| Field | Type | Required | Description |
|---|---|---|---|
visible |
boolean | No | The machine holds the value itself, in its environment variable from its start and in the file /run/secrets/<envName> (mode 0400, owned by root), which is rewritten within a second of each change and removed within a second of a delete or a scope that leaves the machine out. For values the proxy cannot put in, such as a database password or an SSH key. Changed only by a set with the value; false when omitted. |
hosts |
list of string | No | The hosts its value goes to on HTTPS: a name, or *. and a name for every name under it. Required unless visible; refused when visible. |
header |
string | No | The header it is set in on every request to its hosts; when omitted, its placeholder is replaced in the credential headers (Authorization, x-api-key and the like). Hidden secrets only. |
format |
string | No | The header's value, {value} replaced by the secret; {value} when omitted. Hidden secrets only. |
envName |
string | No | The environment variable that holds its placeholder (or, when visible, its value) in each machine it reaches; its name when omitted. When two secrets that reach one machine name the same variable, it holds the one first by name. |
scope |
SecretScope | No | The machines that may use it; every machine of the organization when omitted. |
policies |
SecretPolicies | No | How it may be used. Hidden secrets only. |
Secret
A secret, without its value.
| Field | Type | Required | Description |
|---|---|---|---|
visible |
boolean | No | The machine holds the value itself, in its environment variable from its start and in the file /run/secrets/<envName> (mode 0400, owned by root), which is rewritten within a second of each change and removed within a second of a delete or a scope that leaves the machine out. For values the proxy cannot put in, such as a database password or an SSH key. Changed only by a set with the value; false when omitted. |
hosts |
list of string | No | The hosts its value goes to on HTTPS: a name, or *. and a name for every name under it. Required unless visible; refused when visible. |
header |
string | No | The header it is set in on every request to its hosts; when omitted, its placeholder is replaced in the credential headers (Authorization, x-api-key and the like). Hidden secrets only. |
format |
string | No | The header's value, {value} replaced by the secret; {value} when omitted. Hidden secrets only. |
envName |
string | No | The environment variable that holds its placeholder (or, when visible, its value) in each machine it reaches; its name when omitted. When two secrets that reach one machine name the same variable, it holds the one first by name. |
scope |
SecretScope | No | The machines that may use it; every machine of the organization when omitted. |
policies |
SecretPolicies | No | How it may be used. Hidden secrets only. |
name |
string | Yes | Its name. |
object |
one of secret |
Yes | Always secret. |
state |
one of active, deleted |
Yes | active while requests carry it; deleted once deleted: a delete's answer. |
placeholder |
string | No | What a machine holds in the value's place; none when visible. |
version |
integer | Yes | Raised by each change. |
valueBytes |
integer | No | Its value's length in bytes. |
updatedAt |
string (RFC 3339) | No | When it was last changed. |
deletedAt |
string (RFC 3339) | No | When it was deleted: a delete's answer, its state deleted. |
SecretSet
A secret to store or replace, or, without its value, to change.
| Field | Type | Required | Description |
|---|---|---|---|
visible |
boolean | No | The machine holds the value itself, in its environment variable from its start and in the file /run/secrets/<envName> (mode 0400, owned by root), which is rewritten within a second of each change and removed within a second of a delete or a scope that leaves the machine out. For values the proxy cannot put in, such as a database password or an SSH key. Changed only by a set with the value; false when omitted. |
hosts |
list of string | No | The hosts its value goes to on HTTPS: a name, or *. and a name for every name under it. Required unless visible; refused when visible. |
header |
string | No | The header it is set in on every request to its hosts; when omitted, its placeholder is replaced in the credential headers (Authorization, x-api-key and the like). Hidden secrets only. |
format |
string | No | The header's value, {value} replaced by the secret; {value} when omitted. Hidden secrets only. |
envName |
string | No | The environment variable that holds its placeholder (or, when visible, its value) in each machine it reaches; its name when omitted. When two secrets that reach one machine name the same variable, it holds the one first by name. |
scope |
SecretScope | No | The machines that may use it; every machine of the organization when omitted. |
policies |
SecretPolicies | No | How it may be used. Hidden secrets only. |
value |
string | No | Its value, never answered. Hidden: 1 to 8192 visible ASCII characters and spaces, one line, since it goes into an HTTP header. Visible: 1 byte to 64 KiB of UTF-8 text with no NUL, newlines included (a PEM file, an SSH key, a service account's JSON). With it, the set stores the secret whole, as its fields say. Without it, the set changes only the hosts, policies.rules and scope it names, and keeps the rest: hosts and rules only narrow, since widening needs the value, and so does a visible secret's scope, whose machines hold its value; any other field is refused 400. |
expectedVersion |
integer | No | Replaced only from this version; 409 otherwise. |