Sovrain
  1. Documentation
  2. Identity provider
  3. For developers
  4. Admin API

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 }
  ]
}
FieldTypeNotes
idstringPublic id
namestring
descriptionstringLeft out of the response when the group has none
default_groupbooleanNew members of the organization join this group automatically
built_inbooleantrue for All, Admins and Owners
member_countnumber
membersarrayOnly in GET /groups/{id} and in write responses. Each {id, login, display_name, suspended}.

Built-in groups:

GroupMembers
AllEveryone in the organization. Its members cannot be changed.
AdminsAdministrators: full access to the admin pages and the Admin API
OwnersOwners: 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

FieldTypeRequiredNotes
namestringyesMust be unique in the organization
descriptionstringno
default_groupbooleannoDefault false
{ "name": "Engineering", "description": "People who build things" }

Response 201: the group object with "members": [].

Errors:

StatuserrorWhen
400invalid_requestSend 'name'; an unknown field
500A group with that name already exists

Change a group

PATCH /api/v1/groups/{id}

Scope: groups:write

FieldTypeRequiredNotes
namestringnoLeft out: unchanged
descriptionstringnoLeft out: unchanged. "" empties it; it cannot be set back to none.
default_groupbooleannoLeft out: unchanged

Response 200: the group object.

Errors:

StatuserrorWhen
422refusedA 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:

StatuserrorWhen
422refusedA 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:write can make a user an administrator or an owner.
  • On All it does nothing and answers 204.

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:

StatuserrorWhen
422refusedEveryone is in All; its members cannot be changed.
422refusedRemoving yourself from Owners or Admins: You cannot remove yourself from Owners; another admin must do it.
422refusedRemoving the last active owner from Owners