Skip to content

Key API reference

An API key: what a program, an agent or a CI pipeline calls the API with, acting as the person or agent who made it and never reaching more. Its secret is shown once, when it is made.

Base URL: https://api.withruntime.com. Authentication, idempotency and errors work the same way for every product.

Its states: active, deleted.

Updated .md

Endpoints#

Method Path Description
GET /v2/keys List keys
POST /v2/keys Create a key
POST /v2/keys/{id}:update update
DELETE /v2/keys/{id} Delete a key

List keys#

GET /v2/keys

Lists the organization's live keys, newest first, without their secrets: every key for an owner or an admin, the caller's own otherwise.

Its action, for a key's grant: keys: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 Key, and next, where the next page starts, none on the last.

In v1: GET /v1/keys.

Examples:

Terminalcurl -X GET "https://api.withruntime.com/v2/keys" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.keys.list();
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.keys.list()
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.keys.list
Terminalruntime keys list

Create a key#

POST /v2/keys

Makes a key that acts as the caller, or as one of the organization's agents for the caller, and returns its secret this once. With userCode or authorization, the key goes to the device or OAuth client that asked for it instead, which collects it once from /v2/oauth/token. A key made with a key works until its own end, never past that key's: it lives on when that key is revoked, so a key is rotated by making its next with it.

Its action, for a key's grant: keys:create.

Body: a KeyCreate.

Returns a KeyCreated.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/keys" \  -H "Authorization: Bearer $RUNTIME_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "example" }'
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.keys.create({ name: "example" });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.keys.create(name="example")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.keys.create(name: "example")
Terminalruntime keys create --name example

update#

POST /v2/keys/{id}:update

Renames a key, or sets or removes its caps (maxCost, spendCap); its secret stays as it is. A cap is never set above that of a key it was made with, nor above the caller's own key's, so a key never raises its own caps. An owner or an admin changes any key of the organization; everyone else, their own.

Its action, for a key's grant: keys:update.

Path: id.

Body: a KeyUpdate.

Returns a Key.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/keys/KEY_ID:update" \  -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.keys.update("KEY_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.keys.update("KEY_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.keys.update("KEY_ID")
Terminalruntime keys update KEY_ID

Delete a key#

DELETE /v2/keys/{id}

Revokes a key: refused from its next call, with the hand-off tokens made from it; a key made with it works on. An owner or an admin revokes any key of the organization; everyone else, their own. Revoked again, it returns 404.

Its action, for a key's grant: keys:delete.

Path: id.

Returns a Key.

In v1: DELETE /v1/keys/{id}.

Examples:

Terminalcurl -X DELETE "https://api.withruntime.com/v2/keys/KEY_ID" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.keys.delete("KEY_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.keys.delete("KEY_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.keys.delete("KEY_ID")
Terminalruntime keys delete KEY_ID

Objects#

Key

An API key, without its secret.

Field Type Required Description
id string Yes Its ID.
object one of key Yes Always key.
name string Yes Its name, as its maker gave it.
state one of active, deleted Yes active while it works; deleted once revoked: a delete's answer.
accountId string No The person it acts as or for.
agentId string No The agent or CI pipeline it acts as.
projectId string No The one project it acts in; every project its holder reaches when omitted.
createdAt string (RFC 3339) Yes When it was made.
expiresAt string (RFC 3339) No When it stops working; never when omitted.
lastUsedAt string (RFC 3339) No When it was last used.
maxCost string (US dollars, decimal) No The most one request made with it commits, in US dollars.
spendCap string (US dollars, decimal) No The most the sandboxes made with it, with those of every key made with it, may spend over spendCapWindowSeconds, in US dollars.
spendCapWindowSeconds integer No The rolling window spendCap counts over, in seconds.
spent string (US dollars, decimal) No What it spent over spendCapWindowSeconds (the last 24 hours when it has no spendCap), in US dollars, as spendCap counts it: its sandboxes' and those of every key made with it. Listed and updated keys only.
deletedAt string (RFC 3339) No When it was revoked: a delete's answer, its state deleted.

KeyAuthorization

An OAuth client's request for a key, as /v2/oauth/authorize received it.

Field Type Required Description
clientId string Yes The client's client_id.
redirectUri string Yes Where the client is sent back: one of its redirect URIs.
codeChallenge string Yes Its S256 code_challenge.
state string No Its state, sent back unchanged.

KeyCreate

A key to make.

Field Type Required Description
name string Yes Its name. At least 1 character. At most 64 characters.
projectId string No Held to this one project (Growth and up); every project its holder reaches when omitted.
agentId string No One of the organization's agents or CI pipelines it acts as, for the caller; the caller itself when omitted.
expiresInSeconds integer No Seconds until it stops working; never when omitted. At least 60. At most 31536000.
maxCost string (US dollars, decimal) No The most one request made with it may commit, in US dollars ("5.00"): one asking more is refused 403, and a create that names no maxCost gets this one. Made with a key that has one, at most that key's.
spendCap string (US dollars, decimal) No The most the sandboxes made with it, with those of every key made with it, may spend over spendCapWindowSeconds, in US dollars, as billed: once reached, a create is refused 403 until the window passes it, and a create that names no maxCost gets what is left as its maxCost. Running sandboxes may pass it. Made with a key that has one, at most that key's, and counted in it too.
spendCapWindowSeconds integer No The rolling window spendCap counts over, in seconds; a day when omitted. At least 60. At most 2592000.
userCode string No The code a device shows (OAuth 2.0 device flow, RFC 8628): the key goes to that device, never in this answer.
authorization KeyAuthorization No An OAuth client's request (authorization code with PKCE): the key goes to that client, never in this answer.

KeyCreated

A key just made, with its secret: shown this once, never again.

Field Type Required Description
id string Yes Its ID.
object one of key Yes Always key.
name string Yes Its name, as its maker gave it.
state one of active, deleted Yes active while it works; deleted once revoked: a delete's answer.
accountId string No The person it acts as or for.
agentId string No The agent or CI pipeline it acts as.
projectId string No The one project it acts in; every project its holder reaches when omitted.
createdAt string (RFC 3339) Yes When it was made.
expiresAt string (RFC 3339) No When it stops working; never when omitted.
lastUsedAt string (RFC 3339) No When it was last used.
maxCost string (US dollars, decimal) No The most one request made with it commits, in US dollars.
spendCap string (US dollars, decimal) No The most the sandboxes made with it, with those of every key made with it, may spend over spendCapWindowSeconds, in US dollars.
spendCapWindowSeconds integer No The rolling window spendCap counts over, in seconds.
spent string (US dollars, decimal) No What it spent over spendCapWindowSeconds (the last 24 hours when it has no spendCap), in US dollars, as spendCap counts it: its sandboxes' and those of every key made with it. Listed and updated keys only.
deletedAt string (RFC 3339) No When it was revoked: a delete's answer, its state deleted.
secret string No The key itself, to send as Authorization: Bearer <secret>; omitted for a key a device or an OAuth client collects.
redirectTo string No For an OAuth client's key: where to send the person, with the code the client exchanges for it.

KeyUpdate

A change to a key: each field left out stays as it is.

Field Type Required Description
name string No Its name. At least 1 character. At most 64 characters.
maxCost string (US dollars, decimal) No The most one request made with it may commit, in US dollars ("5.00"). Never more than a key it was made with, nor than the key that changes it: a key never raises its own caps.
spendCap string (US dollars, decimal) No The most the sandboxes made with it, with those of every key made with it, may spend over spendCapWindowSeconds, in US dollars, as billed. Never more than a key it was made with, nor than the key that changes it.
spendCapWindowSeconds integer No The rolling window spendCap counts over, in seconds; kept when omitted, a day for a key that had no spendCap. At least 60. At most 2592000.
remove list of one of maxCost, spendCap No Caps to remove: maxCost, spendCap. The key is then held only by the caps of the keys it was made with and of its holder's grants.
Try it on your own work.Signing up takes no card. Your first sandbox asks for one, and the trial starts then. Or paste the setup prompt into your agent.
Start your free trial