Roles API
Your workspace’s own roles: what each may do, and changing them.
Endpoints
/api/v1/roles/listEvery role of this workspace: the four built-in ones first (ids owner, admin, editor, viewer), then its own roles A-Z. Each: id, name, sentence, builtIn, level (admin, builder or reader for a member's role), lines (the keys of the permission lines it holds), lineLabels (the same lines as { key, label }, the label is what the person reads), people (how many active members have it), mayChange (whether you may edit, rename and delete it), starterUpdate (null, or on a copy of a starter role that Serenities has since changed: { gained, lost } lines, { key, label }; then roles_applyStarter or roles_keepStarter) and newLines (permission lines added since the role was saved, all off on it). Also starters: the Serenities starter roles to copy with roles_copyStarter (key, name, sentence, level, version, lines).
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/roles/list \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{}'/api/v1/roles/getOne role (params: roleId, from roles_list): id, name, sentence, builtIn, lines (keys) and lineLabels ({ key, label } per line). roles_get with roleId "admin" lists every line a role can hold, each key with its label: the full list of keys roles_create and roles_update take.
Parameters
roleId | stringrequired |
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/roles/get \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"roleId": "example"
}'/api/v1/roles/previewChangeWhat saving these lines on one of this workspace's own roles would change, without saving (params: roleId, lines = the keys it should hold): gained and lost lines ({ key, label }), people on it now ({ count, names }) and its open invitations ({ count }).
Parameters
roleId | stringrequired | |
lines | arrayrequired |
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/roles/previewChange \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"roleId": "example",
"lines": {}
}'/api/v1/roles/createMake a role (params: parentId = the role it copies, a built-in id or one of this workspace's; name, 1-40 characters, not a built-in role's name; sentence?; lines = the keys of the permission lines it holds; every key and its label come from roles_get with roleId "admin" (lineLabels), and an unknown key is refused naming the nearest real ones). A line that needs another line (e.g. "Turn agents on" needs "Create and change agents") is refused unless both are listed, naming each pair, and nothing is saved. Some lines bundle several things: "Edit and publish sites" is ONE line, and approving agents' waiting steps is part of "Turn agents on (schedules, webhooks, approvals)" today. Only lines the parent role has and you hold yourself; a role at the admin level (it reaches everything) only the workspace's account holder makes. Nobody has it yet, so it changes nobody's rights: it is done at once. Returns { id, name, gives }: gives is every permission line the role holds, each { key, label }, in the catalogue's order. Show the person what you made as a short table of those labels (what the role can do, in plain words), never the keys.
Parameters
parentId | stringrequired | |
name | stringrequired | |
sentence | string | |
lines | arrayrequired |
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/roles/create \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"parentId": "example",
"name": "example",
"sentence": "example"
}'/api/v1/roles/updateSave a role's lines (params: roleId, lines = every key it should hold; the same keys and the same rule as roles_create: a line listed without a line it needs is refused and nothing changes). Only this workspace's own roles: a built-in one (owner, admin, editor, viewer) can't be changed, so copy it with roles_create and change the copy. Lowering (taking lines away) is done at once and is live for the people on it at their next step; a role nobody has or is invited as is changed at once too. Giving a role someone has MORE lines (a raise) changes other people's rights, so nothing changes yet: the answer is { applied: false, pendingChange } and the change waits as an approval card the person who asked approves in the dashboard (the card in the Serenities chat, or its approveLink); never say it is done. pendingChanges_status with its id says what became of it. Renaming is roles_rename, done at once. Returns { ok } (with notice when it applied at once), or { applied: false, pendingChange } for a raise.
Parameters
roleId | stringrequired | |
lines | arrayrequired |
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/roles/update \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"roleId": "example",
"lines": {}
}'/api/v1/roles/renameRename a role and set its sentence (params: roleId, name, sentence?). Its people and lines stay.
Parameters
roleId | stringrequired | |
name | stringrequired | |
sentence | string |
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/roles/rename \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"roleId": "example",
"name": "example",
"sentence": "example"
}'/api/v1/roles/deleteDelete a role nobody has (params: roleId). Refused while a person has it or an invitation is for it, naming them: move them to another role first. Act only on what the person named or picked.
Parameters
roleId | stringrequired |
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/roles/delete \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"roleId": "example"
}'/api/v1/roles/copyStarterMake a new role from a Serenities starter role (params: starter = a key from roles_list's starters; name, 1-40 characters, not a built-in role's name; sentence?, the starter's when left out). The new role is the workspace's own, with exactly the starter's lines; nobody has it yet, so it is done at once. Returns { id, name, gives } (gives = its lines, { key, label }): show the person that table.
Parameters
starter | stringrequired | |
name | stringrequired | |
sentence | string |
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/roles/copyStarter \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"starter": "example",
"name": "example",
"sentence": "example"
}'/api/v1/roles/applyStarterBring a copy of a starter role up to date with the starter (params: roleId; roles_list shows starterUpdate { gained, lost } on such a role). Taking lines away, or a role nobody has, is done at once. If it GIVES the people on the role more (a role someone has or is invited as), nothing changes yet: the answer is { applied: false, pendingChange } and the change waits as an approval card the person who asked answers with Allow (the card in the Serenities chat, or its approveLink); never say it is done. pendingChanges_status with its id says what became of it. Otherwise returns { ok, gained, lost }.
Parameters
roleId | stringrequired |
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/roles/applyStarter \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"roleId": "example"
}'/api/v1/roles/keepStarterKeep a copy of a starter role as it is after the starter changed (params: roleId): the "starter updated" notice goes, its lines stay. Changes nobody's rights. Returns { ok }.
Parameters
roleId | stringrequired |
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/roles/keepStarter \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"roleId": "example"
}'