Skip to content

Identity API reference

An agent or CI pipeline: who a key acts as besides a person, holding grants of its own.

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/identities List identities
POST /v2/identities/{id}:update update
DELETE /v2/identities/{id} Delete a identity

List identities#

GET /v2/identities

Lists the organization's agents and CI pipelines, by name.

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

Examples:

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

update#

POST /v2/identities/{id}:update

Renames an agent or CI pipeline; its keys and grants stay as they are. A name another of its kind has returns 409.

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

Path: id.

Body: a Rename.

Returns a Identity.

Examples:

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

Delete a identity#

DELETE /v2/identities/{id}

Deletes an agent or CI pipeline and frees its name, with its grants and keys: refused from their next call. The caller needs grants:delete as well, as the grants go with it. What it made stays. Deleted again, it returns 404.

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

Path: id.

Returns a Identity.

Examples:

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

Objects#

Identity

An agent or CI pipeline: who a key acts as, besides a person.

Field Type Required Description
id string Yes Its ID, a key's agentId.
object one of identity Yes Always identity.
kind one of agent, ci Yes agent or ci.
name string Yes Its name, unique in the organization for its kind.
createdAt string (RFC 3339) Yes When it was made.
state one of active, deleted Yes active; deleted once deleted: a delete's answer.
deletedAt string (RFC 3339) No When it was deleted: a delete's answer, its state deleted.

Rename

A new name; everything else stays as it is.

Field Type Required Description
name string Yes Its name. At least 1 character. At most 64 characters.
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