Reference
Groups
Admin API endpoints for listing, creating, changing and deleting groups and for adding and removing members.
Endpoints under https://acme.sovrain.net/api/v1/groups. Authentication, conventions and the error format are on
Admin API.
The group object
{
"id": "SuT8oWQLVMPzwYQyhKjm32",
"name": "Engineering",
"description": "People who build things",
"default_group": false,
"built_in": false,
"member_count": 2,
"members": [
{ "id": "FomjVqEuLmL5CBPAfVwYK2", "login": "anna@acme.example", "display_name": "Anna Nowak", "suspended": false },
{ "id": "7u5yQZMoFbZ9C4bnwi3Nph", "login": "bob", "display_name": null, "suspended": false }
]
}
| Field | Type | Notes |
|---|---|---|
id | string | Public id |
name | string | |
description | string | Left out of the response when the group has none |
default_group | boolean | New members of the organization join this group automatically |
built_in | boolean | true for All, Admins and Owners |
member_count | number | |
members | array | Only in GET /groups/{id} and in write responses. Each {id, login, display_name, suspended}. |
Built-in groups:
| Group | Members |
|---|---|
All | Everyone in the organization. Its members cannot be changed. |
Admins | Administrators: full access to the admin pages and the Admin API |
Owners | Owners: as administrators, and only owners can import a backup and reset another administrator’s sign-in |
Groups do not contain other groups.
List groups
GET /api/v1/groups
Scope: groups:read
Response 200, all groups in one page, without members:
{
"items": [
{
"id": "gtEPGF6QcVzZ7nhfkqdwQ8",
"name": "All",
"description": "Everyone in this organization",
"default_group": true,
"built_in": true,
"member_count": 3
},
{
"id": "x5myRBXWBicHk3YTkW65gi",
"name": "Admins",
"description": "Organization administrators",
"default_group": false,
"built_in": true,
"member_count": 0
},
{
"id": "umEuh8qPkaww3FYPmiCRiF",
"name": "Owners",
"description": "Organization owners",
"default_group": false,
"built_in": true,
"member_count": 1
}
],
"next_cursor": null
}
Get a group
GET /api/v1/groups/{id}
Scope: groups:read
Response 200: the group object with members.
Errors: 404 not_found for an unknown group.
Create a group
POST /api/v1/groups
Scope: groups:write
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes | Must be unique in the organization |
description | string | no | |
default_group | boolean | no | Default false |
{ "name": "Engineering", "description": "People who build things" }
Response 201: the group object with "members": [].
Errors:
| Status | error | When |
|---|---|---|
| 400 | invalid_request | Send 'name'; an unknown field |
| 500 | A group with that name already exists |
Change a group
PATCH /api/v1/groups/{id}
Scope: groups:write
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | no | Left out: unchanged |
description | string | no | Left out: unchanged. "" empties it; it cannot be set back to none. |
default_group | boolean | no | Left out: unchanged |
Response 200: the group object.
Errors:
| Status | error | When |
|---|---|---|
| 422 | refused | A built-in group: Cannot update built-in or unknown group: id=1 |
Delete a group
DELETE /api/v1/groups/{id}
Scope: groups:delete
Response 204. Members are not deleted. Applications that the group gave access to stop admitting its members,
unless another group gives them access.
Errors:
| Status | error | When |
|---|---|---|
| 422 | refused | A built-in group: Cannot delete built-in or unknown group: id=1 |
Add a member
PUT /api/v1/groups/{id}/members/{userId}
Scope: groups:write
No body. Response 204, also when the user already is a member.
- Works on Admins and Owners: a token with
groups:writecan make a user an administrator or an owner. - On
Allit does nothing and answers204.
Errors: 404 not_found for an unknown group or user.
Remove a member
DELETE /api/v1/groups/{id}/members/{userId}
Scope: groups:write
No body. Response 204, also when the user was not a member.
A user who leaves both Owners and Admins loses admin access, and that user’s Admin API grants are revoked.
Errors:
| Status | error | When |
|---|---|---|
| 422 | refused | Everyone is in All; its members cannot be changed. |
| 422 | refused | Removing yourself from Owners or Admins: You cannot remove yourself from Owners; another admin must do it. |
| 422 | refused | Removing the last active owner from Owners |