Users

In Cerby, users are individuals who have access to a workspace through a user account and can create, protect, and manage items. A user object contains information about the name, email, workspace role, and other relevant attributes of a user.

A user object is created in Cerby when you perform any of the following actions:

• Provision a user in Cerby from your corporate identity provider (IdP), such as Okta or Entra ID (formerly Azure AD).

• Invite a user to join a local user workspace with an identity managed by Cerby.

• Invite a user to join a workspace as a guest user with an identity managed by Cerby.

With the Cerby API, you can retrieve all users or specific users by providing their ID.

Important: You can only retrieve users if you have the workspace Admin, Super Admin, or Owner role. Your permissions are determined by your API or bearer token based on Cerby’s RBAC system.

List users

get

With a GET request to the /users endpoint, you can retrieve the list of all users in your workspace.

Important: The API scope required to use this endpoint is: User data.

Query parameters

page[number]integer · min: 1Optional

The page number to retrieve in the paginated result set.

Default: 1

page[size]integer · min: 1 · max: 100Optional

The number of items to return per page.

Default: 25

filterstringOptional

The user's full name or email to filter the response.

mfaStatusbooleanOptional

When set to true, includes MFA status details for each user. If omitted or false, the mfaStatus attribute is null.

Responses

200

OK

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

get

/users

HTTPcURLJavaScriptPython

GET /api/v1/users HTTP/1.1
Host: my-workspace.cerby.com
Accept: */*

{
  "data": [
    {
      "attributes": {
        "createdAt": "2024-01-04T15:36:54+00:00",
        "email": "[e-mail]",
        "firstName": "Joe",
        "isGuest": false,
        "lastName": "Doe",
        "mfaStatus": {
          "mfaEnabled": true,
          "mfaEnrollmentDate": "2024-05-10T15:30:00+00:00"
        },
        "role": "workspace_owner",
        "status": "live",
        "updatedAt": "2024-07-08T19:30:56+00:00"
      },
      "id": "1234c85b-1234-1234-1234-7c886800abcd",
      "type": "user"
    },
    {
      "attributes": {
        "createdAt": "2024-01-22T20:54:33+00:00",
        "email": "[e-mail]",
        "firstName": "Kevin",
        "isGuest": false,
        "lastName": "Example",
        "mfaStatus": null,
        "role": "workspace_super_admin",
        "status": "live",
        "updatedAt": "2024-09-24T18:41:23+00:00"
      },
      "id": "1234c85b-1234-1234-1234-7c886800abcd",
      "type": "user"
    },
    {
      "attributes": {
        "createdAt": "2021-10-19T17:58:43+00:00",
        "email": "[e-mail]",
        "firstName": "Rose",
        "isGuest": false,
        "lastName": "Poe",
        "mfaStatus": null,
        "role": "workspace_owner",
        "status": "live",
        "updatedAt": "2024-03-25T15:17:41+00:00"
      },
      "id": "aab12343fbc-1234-1234-1234-3fb6573fabcd",
      "type": "user"
    }
  ],
  "links": {
    "next": "/api/v1/users?page%5Bnumber%5D=2&page%5Bsize%5D=3",
    "previous": null,
    "self": "/api/v1/users?page%5Bnumber%5D=1&page%5Bsize%5D=3"
  },
  "meta": {
    "page": {
      "maxSize": 100,
      "total": 202
    }
  }
}

Retrive user by ID

get

With a GET request to the /users/{id} endpoint, you can retrieve the information of a user by providing their ID.

Important: The API scope required to use this endpoint is: User data.

Path parameters

idstring · uuidOptional

The unique identifier of the user.

Query parameters

mfaStatusbooleanOptional

When set to true, includes MFA status details for the user. If omitted or false, the mfaStatus attribute is null.

Responses

200

OK

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

get

/users/{id}

HTTPcURLJavaScriptPython

GET /api/v1/users/{id} HTTP/1.1
Host: my-workspace.cerby.com
Accept: */*

{
  "data": {
    "attributes": {
      "createdAt": "2024-01-04T15:36:54+00:00",
      "email": "[e-mail]",
      "firstName": "Joe",
      "isGuest": false,
      "lastName": "Doe",
      "mfaStatus": {
        "mfaEnabled": true,
        "mfaEnrollmentDate": "2024-05-10T15:30:00+00:00"
      },
      "role": "workspace_owner",
      "status": "live",
      "updatedAt": "2024-07-08T19:30:56+00:00"
    },
    "id": "1234c85b-1234-1234-1234-7c886800abcd",
    "type": "user"
  }
}