Role API reference
One of the organization's own roles: the actions a grant of it allows. The built-in roles (owner, admin, developer, viewer, billing) are not listed here.
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/roles |
List roles |
POST |
/v2/roles/{id}:update |
update |
DELETE |
/v2/roles/{id} |
Delete a role |
List roles#
GET /v2/roles
Lists the organization's own roles, by name.
Its action, for a key's grant: roles: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 Role, and next, where the next page starts, none on the last.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/roles" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.roles.list();Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.roles.list()rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.roles.listTerminalruntime roles listupdate#
POST /v2/roles/{id}:update
Renames a role; its actions and its grants stay as they are. A built-in role's name, or another role's, returns 409.
Its action, for a key's grant: roles:update.
Path: id.
Body: a Rename.
Returns a Role.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/roles/ROLE_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.roles.update("ROLE_ID", { name: "example" });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.roles.update("ROLE_ID", name="example")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.roles.update("ROLE_ID", name: "example")Terminalruntime roles update ROLE_ID --name exampleDelete a role#
DELETE /v2/roles/{id}
Deletes a role and frees its name, with the grants and invitations that give it. The caller needs grants:delete as well, as the grants go with it. Deleted again, it returns 404.
Its action, for a key's grant: roles:delete.
Path: id.
Returns a Role.
Examples:
Terminalcurl -X DELETE "https://api.withruntime.com/v2/roles/ROLE_ID" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.roles.delete("ROLE_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.roles.delete("ROLE_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.roles.delete("ROLE_ID")Terminalruntime roles delete ROLE_IDObjects#
Role
One of the organization's own roles: the actions a grant of it allows.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Its ID. |
object |
one of role |
Yes | Always role. |
name |
string | Yes | Its name, unique in the organization. |
actions |
list of string | Yes | The actions it holds, each product:action, product:* or *. |
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. |