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.
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.listTerminalruntime identities listupdate#
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 exampleDelete 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_IDObjects#
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. |