Welcome to the Cerby developer portal!

Cerby is an identity, access, and password management platform for disconnected applications that don’t support common identity and security standards. This developer portal contains self-serve tools you can use to seamlessly integrate our services into your applications and systems.

API reference

The Cerby API implements a set of rules and protocols that enable your company’s custom applications to communicate with our platform. To interact with our API, you must send a request to a specific endpoint, which our API processes to return a JSON-encoded response.

The following are the collection data available in our API:

Accounts
Secrets
Collections
Users
Teams
Integrations
Jobs

The Cerby API follows RESTful principles and the OpenAPI 3.0 Specifications and communicates over HTTPS for secure data transmission.

The base URL is the following:

https://my-workspace.cerby.com/api/v1/

You must replace my-workspace with the name of your workspace.

Authentication

The Cerby API uses a Cerby API key to authorize requests. You can only generate and retrieve keys from the Cerby web app after authenticating into your corporate identity provider, such as Okta or Entra ID, to access your workspace.

Based on Cerby’s role-based access control (RBAC) system, the API key you use for authentication determines the endpoints and data you can access depending on your workspace and item role. Therefore, you must send the X-API-Key parameter in the header of each API request.

To generate and retrieve a key, you must follow the instructions in the article Generate an API key and select the required scopes for the endpoint you plan to use.

The following are the available scopes:

Read activities: Enables reading activity data.
Read items: Enables reading account, secret, and collection data.
Read accounts: Enables reading account data.
Read secrets: Enables reading secret data.
Read users: Enables reading user and team data.
Read integrations: Enables reading integration and entitlement data.
Write integrations: Enables writing integration and entitlement data.
Read automated jobs: Enables reading automated job data.
Write automated jobs: Enables writing automated job data.

Requests

A typical Cerby API request has the following structure:

GET /{resource} Host: https://{my-workspace}.cerby.com/api/v1/{resource}/{path-parameter}?{query-parameter}={custom-value} Header: X-API-Key

The following are the main components of the request:

HTTP method
URL structure
Header
Body

The following sections explain each component.

HTTP method

The Cerby API uses the following HTTP methods to define the type of operation to perform:

GET: Retrieves data from the server. For example, GET /users to list all users in your Cerby workspace.
PATCH: Sends data to the server to update an existing resource. For example, PATCH /integrations/{id}/users/{userId} to update a user’s entitlements in an integration.

URL structure

The full URL of an endpoint in the Cerby API is the following:

https://{my-workspace}.cerby.com/api/v1/{resource}/{path-parameter}?{query-parameter}={custom-value}

The following is the structure of the URL:

Protocol: The secure communication method to transmit data is HTTPS.
Domain: The base URL is {my-workspace}.cerby.com/api/v1. You must replace {my-workspace} with the name of your workspace.
Resource: The specific Cerby resource being accessed.
Parameter: The additional data to specify the resource you want to access, filter, paginate, or sort in the response. The Cerby API includes the following parameter types:
- Path parameter
- Query parameter

Path parameter

See an example of a request including path parameters in the JSON tab.

https://{my-workspace}.cerby.com/api/v1/accounts/123456a7-1234-419f-123a-ae3cd6d12341

Path parameters specify the resource you want to access with the endpoint. In the Cerby API, path parameters are embedded in the URL.

Query parameter

See an example of a request including query parameters in the JSON tab.

https://{my-workspace}.cerby.com/api/v1/accounts?page[number]=1&page[size]=30&filter[application]=instagram,unmanaged&filter[status]=enabled

Query parameters paginate, filter, or sort the results of the request. In the Cerby API, query parameters are appended to the URL after a question mark character (?) and separated by ampersands (&).

The following are the common query parameters in the Cerby API endpoints:

Pagination
- page[number]: The page number you want to retrieve in the paginated result set.
- page[size]: The number of items you want to retrieve per page.
Filtering
- filter[application]: The comma-separated list of applications to filter their associated accounts.
- filter[status]: The status value to filter accounts. The possible values are: enabled and disabled.
Sorting
- sort: The criteria for sorting the requested results alphabetically based on an attribute.
  NOTE: Append the minus (-) character before the attribute to sort in ascending order. For example, sort=-created_at.

The header provides additional metadata for the request to the endpoint. In the Cerby API, you must use the X-API-Key header.

Body

The body contains the data you must send to the server for the POST and PATCH methods. The body format in the Cerby API is JSON.

Responses

See a typical Cerby API response structure in the JSON tab.

HTTP/1.1 200 OK
Content-Type: application/json
{
    "data": {
        "id": 1,
        "attributes": {
            "name": "John Doe",
            "email": "john@example.com"
         },
         "type": "user"
    },
    "links": {
        "self": "string",
        "next": "string"
    },
    "meta": {
        "page": {
           "maxSize": 0,
           "total": 0
        }
    }
}

The following are the main components of the response:

Status code: The result of the request, such as 200 (OK) or 404 (Not found). Refer to the Errors section to read the specifications of each response status code.
Headers: The metadata for the response. For example, Content-Type.
Body: The actual data returned in JSON format. The Cerby API response can include the following main properties:

Data object

The data object contains the primary information that the client requested.

Links object

See an example of the links object in the JSON tab.

"links": {
        "next": "/api/v1/teams?page[number]=12&page[size]=3",
        "previous": "/api/v1/teams?page[number]=10&page[size]=3",
        "self": "/api/v1/teams?page[number]=11&page[size]=3"
    }

IMPORTANT: The above example shows the URIs decoded for better readability. In practice, these URIs contain percent-encoded characters.

The links object provides the related URLs that can be helpful for navigation.

The following table describes the attributes of a links object:

Attribute		Description
`links` object		The attributes of the `links` object.
	`next` string	The next page of results.
	`previous` string	The previous page of results.
	`self` string	The self reference to the endpoint you are calling.

Meta object

See an example of the meta object in the JSON tab.

"meta": {
        "page": {
            "maxSize": 100,
            "total": 10
        }
    }

The meta object contains metadata about the response that provides additional context or information about the data object.

The following table describes the attributes of a links object:

Attribute			Description
`meta` object			The attributes of the `meta` object.
	`page` object		The attributes of the page in the response.
		`maxSize` number	The maximum number of items that can be returned per page.
		`total` number	The total number of items available across all pages.

Response status codes

See an example of a response with the 400 status in the JSON tab.

{
    "errors": [
        {
            "code": "validation_error",
            "detail": "value is not a valid enumeration member; permitted: 'enabled', 'disabled'",
            "meta": {
                "ctx": {
                    "enum_values": [
                        "enabled",
                        "disabled"
                    ]
                },
                "loc": [
                    "filter[status]",
                    0
                ],
                "msg": "value is not a valid enumeration member; permitted: 'enabled', 'disabled'",
                "type": "type_error.enum"
            },
            "status": "400",
            "title": "validation_error"
        }
    ]
}

See an example of a response with the 401 status in the JSON tab.

{
  "errors": [
    {
      "code": "unauthorized",
      "detail": "Unable to access resource.",
      "meta": null,
      "status": 401,
      "title": "unauthorized"
    }
  ]
}

See an example of a response with the 404 status in the JSON tab.

{
  "errors": [
    {
      "code": "not_found",
      "detail": "Resource not found.",
      "meta": null,
      "status": 404,
      "title": "not_found"
    }
  ]
}

The Cerby API uses the following standard HTTP response codes to identify the status of each API request.

2xx: Indicates successful requests.
4xx: Indicates errors caused by the information provided in the request, such as missing parameters or incorrect IDs.

The following table describes each HTTP response code:

Code	Status	Description
`200`	`OK`	The request has succeeded.
`400`	`Bad request`	The server could not interpret the request due to invalid syntax or missing parameters. Review your request and correct it.
`401`	`Unauthorized`	The request has not been applied because it lacks valid authentication credentials for the target resource. Verify the expiration of your Cerby API key or generate a new one.
`402`	`Request failed`	The request failed due to an unknown error. Ensure that you are using the correct API key and header.
`403`	`Forbidden`	The API key has no permission to perform the request. Verify that your API key has the required scopes.
`404`	`Not found`	The origin server did not find a current representation for the target resource or is not willing to disclose that one exists. Verify your request. IMPORTANT: This status code applies to invalid requests when retrieving items by ID.
`429`	`Too many requests`	The user has sent too many requests in a given amount of time ("rate limiting"). Retry in five minutes.

Accounts

In Cerby, accounts are digital records that contain user login information for a particular app or service provider. An account object contains information about the account label, the app to which the account belongs, the dates when the account was created and last updated, and the user who created and last updated the account.

An account object is created in Cerby when you perform any of the following actions:

Add an account manually through the Cerby web app or mobile app.
Autosave an account at login or signup through the Cerby browser extension
Import items from your password manager.

With the Cerby API, you can retrieve all accounts or specific accounts by providing its ID. To learn more about accounts, refer to the Accounts article collection on the Cerby Help Center.

The account schema

See a sample of the account schema in the JSON tab.

{
   "attributes": {
     "application": "instagram",
     "createdAt": "2007-01-09T15:41:27.000Z",
     "createdBy": "91c14c1e-fdb1-4859-b0b1-e9f12f45abcd",
     "label": "my awesome account",
     "updatedAt": "2007-01-09T15:41:27.000Z",
     "workspace": "my-workspace"
   },
   "id": "12344dba-31e7-41db-9035-9f3a35b884c1",
   "type": "account"
}

The following table describes the attributes of an account object:

Attributes		Description
`attributes` object		The attributes of the account.
	`application` string	The application to which the account belongs.
	`createdAt` string	The date when the account was created in the ISO 8610 format
	`createdBy` string	The ID of the user who created the account.
	`label` string	The name or label of the account./td>
	`updatedAt` string	The date when the account was last updated in the ISO 8610 format
	`workspace` string	The workspace where the account is stored.
`id` string		The unique identifier of the account.
`type` string		The item type is always “account.”

List accounts

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

Query parameters

The following is an example of a request to the endpoint:

https://{my-workspace}.cerby.com/api/v1/accounts?page[size]=3&filter[status]=enabled

curl --location --globoff 'https://{my-workspace}.cerby.com/api/v1/accounts?page[size]=3&filter[status]=enabled' \
--header 'x-api-key: {API key}'

GET /api/v1/accounts?page[size]=3&filter[status]=enabled HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {API key}

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://{my-workspace}.cerby.com/api/v1/accounts?page[size]=3&filter[status]=enabled");
xhr.setRequestHeader("x-api-key", "{api-key}");

xhr.send();

import http.client

conn = http.client.HTTPSConnection("{my-workspace}.cerby.com")
payload = ''
headers = {
  'x-api-key': '{api-key}'
}
conn.request("GET", "/api/v1/accounts?page%5Bsize%5D=3&filter%5Bstatus%5D=enabled", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The following table describes the query parameters of a request:

Parameter	Required	Description
`page[number]` integer	false	The page number to retrieve in a paginated list. The default and minimum value is 1.
`page[size]` integer	false	The number of items to display per page. The default value is 25; the maximum is 100.
`filter[application]` array	false	A comma-separated list of applications.
`filter[status]` array	false	The status value to filter accounts. The possible values are: `enabled` and `disabled`.

Response

See an example of the response in the JSON tab.

{
    "data": [
        {
            "attributes": {
                "application": "unmanaged",
                "createdAt": "2024-07-09T02:30:46+00:00",
                "createdBy": "123456a7-1234-419f-123a-ae3cd6d12341",
                "label": "Acme",
                "updatedAt": "2024-07-09T02:30:46+00:00",
                "workspace": "my-workspace"
            },
            "id": "123456a7-1234-419f-123a-ae3cd6d12350",
            "type": "account"
        },
        {
            "attributes": {
                "application": "twitter",
                "createdAt": "2024-02-01T21:49:17+00:00",
                "createdBy": "123456a7-1234-419f-123a-ae3cd6d12341",
                "label": "myAccount-twitter",
                "updatedAt": "2024-03-25T15:13:09+00:00",
                "workspace": "my-workspace"
            },
            "id": "123456a7-1234-419f-123a-ae3cd6d12360",
            "type": "account"
        },
        {
            "attributes": {
                "application": "mailchimp",
                "createdAt": "2024-05-23T20:24:35+00:00",
                "createdBy": "123456a7-1234-419f-123a-ae3cd6d12341",
                "label": "Mailchimp",
                "updatedAt": "2024-07-23T15:46:51+00:00",
                "workspace": "my-workspace"
            },
            "id": "123456a7-1234-419f-123a-ae3cd6d12345",
            "type": "account"
        }
    ],
    "links": {
        "next": "/api/v1/accounts?page%5Bnumber%5D=2&page%5Bsize%5D=3",
        "previous": null,
        "self": "/api/v1/accounts?page%5Bnumber%5D=1&page%5Bsize%5D=3"
    },
    "meta": {
        "page": {
            "maxSize": 100,
            "total": 18
        }
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The JSON array with the account objects requested on the specified page.	Account schema Links object Meta object
`400`	`Bad request`	The server could not interpret the request due to invalid parameters. Review your request and correct it.	Errors
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors

Retrieve account by ID

With a GET request to the accounts/{id} endpoint, you can retrieve the information of an account by providing its ID.

Path parameters

The following is an example of a request to the endpoint:

https://{my-workspace}.cerby.com/api/v1/accounts/989165cc-112c-4112-a877-e047ffe9abcd

curl --location 'https://{my-workspace}.cerby.com/api/v1/accounts/989165cc-112c-4112-a877-e047ffe9abcd' \
--header 'x-api-key: {api-key}'

GET /api/v1/accounts/989165cc-112c-4112-a877-e047ffe9abcd HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {api-key}

// WARNING: For GET requests, body is set to null by browsers.

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://{my-workspace}.cerby.com/api/v1/accounts/989165cc-112c-4112-a877-e047ffe9abcd");
xhr.setRequestHeader("x-api-key", "{api-key}");

xhr.send();

import http.client

conn = http.client.HTTPSConnection("{my-workspace}.cerby.com")
payload = ''
headers = {
  'x-api-key': '{api-key}'
}
conn.request("GET", "/api/v1/accounts/989165cc-112c-4112-a877-e047ffe9abcd", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The following table describes the path parameters of a request:

Parameter	Required	Description
`id` string	true	The unique identifier of the account.

Response

See an example of the response in the JSON tab.

{
    "data": {
        "attributes": {
            "application": "discord_tenant",
            "createdAt": "2024-08-29T19:15:46.475000+00:00",
            "createdBy": "10b258e4-8454-1234-91a3-cacd42f0abcd",
            "label": "Discord",
            "updatedAt": "2024-08-29T19:33:05.028000+00:00",
            "workspace": "cerby"
        },
        "id": "989165cc-112c-1234-a877-e047ffe9abcd",
        "type": "account"
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The requested account JSON object.	Account schema
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

Secrets

In Cerby, secrets are encrypted digital records that contain sensitive corporate data in text and attached files. A secret object contains information about the secret title, its ID, its category, if it requires a challenge, the workspace where it belongs, the dates when the secret was created and last updated, and the user who created and last updated the secret.

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

Add a secret manually through the Cerby web app or mobile app.
Import items from your password manager.

With the Cerby API, you can retrieve all secrets or specific secrets by providing their ID. To learn more about secrets, refer to the Secrets article collection on the Cerby Help Center.

The secret schema

See an example of the secret schema in the JSON tab.

{
    "attributes": {
        "bodySecretId": "123456a7-1234-419f-123a-ae3cd6d12345",
        "category": "text",
        "createdAt": "2023-07-26T23:33:03.860000+00:00",
        "createdBy": "123456a7-1234-419f-123a-ae3cd6d12345",
        "eventName": "create",
        "requiresIdentityChallenge": false,
        "status": "active",
        "title": "License keys",
        "updatedAt": "2023-07-26T23:33:03.860000+00:00",
        "updatedBy": "123456a7-1234-419f-123a-ae3cd6d12345",
        "version": 1,
        "versionId": "5199654b-cfc8-4624-99f8-4f8a946fae60",
        "workspaceId": "5aab889c-db7d-4164-87b0-e07e57c36007",
        "workspaceName": "cerby"
    },
    "id": "123456a7-1234-419f-123a-ae3cd6d12345",
    "type": "secret"
}

The following table describes the attributes of a secret object:

Attribute		Description
`attributes` object		The attributes of the secret.
	`bodySecretId` string	The unique identifier of the secret.
	`category` string	The category of the secret. The possible values are: `text`, `wifi_password`, `ssh_key`, `database`, `server`, `software_license`, and `custom`.
	`createdAt` string	The date when the secret was created in the ISO 8610 format.
	`createdBy` string	The ID of the user who created the secret.
	`eventName` string	The name of the latest event that occurred for the secret. The possible values are: `create`, `update`, `restore_version`, and `delete`.
	`requiresIdentityChallenge` boolean	The boolean value that indicates whether the secret requires an identity challenge to be opened. `True`, an identity challenge is required; `false`, the challenge is not required.
	`status` string	The status of the secret. The possible values are: `active` and `disabled`.
	`title` string	The title of the secret
	`updatedAt` string	The date when the secret was last updated in the ISO 8610 format.
	`updatedBy` string	The ID of the user who last updated the secret.
	`version` number	The numerical value that indicates the current version of the secret.
	`versionId` string	The unique identifier of the current version of the secret.
	`workspaceId` string	The ID of the workspace where the secret is saved.
	`workspaceName` string	The name of the workspace where the secret is saved.
`id` string		The unique identifier of the secret.
`type` string		The resource type is always "secret."

List secrets

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

Query parameters

The following is an example of a request to the endpoint:

https://{my-workspace}.cerby.com/api/v1/secrets?page[size]=3

curl --location --globoff 'https://{my-workspace}.cerby.com/api/v1/secrets?page[size]=3' \
--header 'x-api-key: {api-key}'

GET /api/v1/secrets?page[size]=3 HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {api-key}

// WARNING: For GET requests, body is set to null by browsers.

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://{my-workspace}.cerby.com/api/v1/secrets?page[size]=3");
xhr.setRequestHeader("x-api-key", "{api-key}");

xhr.send();

import http.client

conn = http.client.HTTPSConnection("{my-workspace}.cerby.com")
payload = ''
headers = {
  'x-api-key': '{api-key}'
}
conn.request("GET", "/api/v1/secrets?page%5Bsize%5D=3", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The following table describes the query parameters of a request:

Parameter	Required	Description
`page[number]` integer	false	The page number to retrieve in a paginated list. The default and minimum value is 1.
`page[size]` integer	false	The number of items to display per page. The default value is 25; the maximum is 100.

Response

See an example of the response in the JSON tab.

{
    "data": [
        {
            "attributes": {
                "bodySecretId": "123456a7-1234-419f-123a-ae3cd6d12345",
                "category": "text",
                "createdAt": "2023-07-26T23:33:03.860000+00:00",
                "createdBy": "123456a7-1234-419f-123a-ae3cd6d12345",
                "eventName": "create",
                "requiresIdentityChallenge": false,
                "status": "active",
                "title": "License keys",
                "updatedAt": "2023-07-26T23:33:03.860000+00:00",
                "updatedBy": "123456a7-1234-419f-123a-ae3cd6d12345",
                "version": 1,
                "versionId": "5199654b-cfc8-4624-99f8-4f8a946fae60",
                "workspaceId": "5aab889c-db7d-4164-87b0-e07e57c36007",
                "workspaceName": "cerby"
            },
            "id": "123456a7-1234-419f-123a-ae3cd6d12345",
            "type": "secret"
        },
        {
            "attributes": {
                "bodySecretId": "123456a7-1234-419f-123a-ae3cd6d12345",
                "category": "text",
                "createdAt": "2023-07-27T19:06:06.860000+00:00",
                "createdBy": "123456a7-1234-419f-123a-ae3cd6d12345",
                "eventName": "create",
                "requiresIdentityChallenge": true,
                "status": "active",
                "title": "A new secret",
                "updatedAt": "2023-07-27T19:06:06.860000+00:00",
                "updatedBy": "123456a7-1234-419f-123a-ae3cd6d12345",
                "version": 0,
                "versionId": "123456a7-1234-419f-123a-ae3cd6d12345",
                "workspaceId": "123456a7-1234-419f-123a-ae3cd6d12345",
                "workspaceName": "cerby"
            },
            "id": "123456a7-1234-419f-123a-ae3cd6d12345",
            "type": "secret"
        },
        {
            "attributes": {
                "bodySecretId": "123456a7-1234-419f-123a-ae3cd6d12345",
                "category": "text",
                "createdAt": "2023-10-04T02:00:06.860000+00:00",
                "createdBy": "123456a7-1234-419f-123a-ae3cd6d12345",
                "eventName": "create",
                "requiresIdentityChallenge": false,
                "status": "active",
                "title": "secure note test - 1 (copy)",
                "updatedAt": "2023-10-04T02:00:06.860000+00:00",
                "updatedBy": "123456a7-1234-419f-123a-ae3cd6d12345",
                "version": 0,
                "versionId": "123456a7-1234-419f-123a-ae3cd6d12345",
                "workspaceId": "123456a7-1234-419f-123a-ae3cd6d12345",
                "workspaceName": "cerby"
            },
            "id": "123456a7-1234-419f-123a-ae3cd6d12345",
            "type": "secret"
        }
    ],
    "links": {
        "next": "/api/v1/secrets?page%5Bnumber%5D=2&page%5Bsize%5D=3",
        "self": "/api/v1/secrets?page%5Bnumber%5D=1&page%5Bsize%5D=3"
    },
    "meta": {
        "page": {
            "maxSize": 100,
            "total": 10
        }
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The JSON array with the account objects requested on the specified page.	Secret schema Meta object Links object
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

Retrieve secret by ID

With a GET request to the secrets/{id} endpoint, you can retrieve the information of a secret by providing its ID.

Path parameters

The following is an example of a request to the endpoint:

https://{my-workspace}.cerby.com/api/v1/secrets/123456a7-1234-419f-123a-ae3cd6d12345

curl --location 'https://{my-workspace}.cerby.com/api/v1/secrets/123456a7-1234-419f-123a-ae3cd6d12345' \
--header 'x-api-key: {api-key}'

GET /api/v1/secrets/123456a7-1234-419f-123a-ae3cd6d12345 HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {api-key}

// WARNING: For GET requests, body is set to null by browsers.

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://{my-workspace}.cerby.com/api/v1/secrets/123456a7-1234-419f-123a-ae3cd6d12345");
xhr.setRequestHeader("x-api-key", "{api-key}");

xhr.send();

import requests

url = "https://{my-workspace}.cerby.com/api/v1/secrets/123456a7-1234-419f-123a-ae3cd6d12345"

payload = {}
headers = {
  'x-api-key': '{api-key}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

The following table describes the path parameters of a request:

Parameter	Required	Description
id string	true	The unique identifier of the secret.

Response

See an example of the response in the JSON tab.

{
    "data": {
        "attributes": {
            "bodySecretId": "123456a7-1234-419f-123a-ae3cd6d12345",
            "category": "text",
            "createdAt": "2023-10-04T02:00:06.860000+00:00",
            "createdBy": "123456a7-1234-419f-123a-ae3cd6d12325",
            "eventName": "create",
            "requiresIdentityChallenge": false,
            "status": "active",
            "title": "License keys",
            "updatedAt": "2023-10-04T02:00:06.860000+00:00",
            "updatedBy": "123456a7-1234-419f-123a-ae3cd6d12325",
            "version": 1,
            "versionId": "123456a7-1234-419f-123a-ae3cd6d12345",
            "workspaceId": "123456a7-1234-419f-123a-ae3cd6d54321",
            "workspaceName": "cerby"
        },
        "id": "7b968a1a-228a-4336-8556-1eea12345cba",
        "type": "secret"
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The requested secret JSON object.	Secret schema
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

Collections

In Cerby, collections are groups of accounts, secrets, and subcollections created to organize and categorize saved items. A collection object contains information about the collection label, the number of accounts and secrets within it, the dates when the collection was created and last updated, and the user who created and last updated the collection and their role.

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

Add a collection manually through the Cerby web app.
Import vaults or folders from your password manager.

With the Cerby API, you can retrieve all collections or specific collections by providing their ID. To learn more about collections, refer to the Collections article collection on the Cerby Help Center.

The collection schema

See a sample of the collection schema in the JSON tab.

{
    "attributes": {
        "createdAt": "2024-07-12T23:10:27+00:00",
        "createdBy": "1cc381f7-1234-1234-ac7b-ae3cd6d1abcd",
        "meta": {},
        "name": "Employee",
        "roles": [
            "collection_owner"
        ],
        "status": "enabled",
        "updatedAt": "2024-07-12T23:10:27+00:00",
        "updatedBy": "1cc381f7-1234-1234-ac7b-ae3cd6d1abcd"
    },
    "id": "2e376b17-1234-1234-8f72-4bb7d931abcd",
    "type": "collections"
 }

The following table describes the attributes of the collection object:

Attribute		Description
`attributes` object		The attributes of the collection.
	`createdAt` string	The date when the collection was created in the [ISO 8610 format](https://www.iso.org/iso-8601-date-and-time-format.html).
	`createdBy` string	The ID of the user who created the collection.
	`meta` object	The object to provide additional information about a collection using key-value pairs.
	`name` string	The name of the collection.
	`roles` array	The roles of the users with shared access to the collection. The possible values are: collection_owner and collection_collaborator.
	`status` string	The status of the collection. The possible values are: enabled and disabled.
	`updatedAt` string	The date when the collection was last updated in the ISO 8610 format.
	`updatedBy` string	The ID of the user who last updated the collection.
`id` string		The unique identifier of the collection.
`type` string		The item type is always “collections.”

List collections

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

Query parameters

The following is an example of a request to the endpoint:

https://{my-workspace}.cerby.com/api/v1/collections?page[size]=3

curl --location --globoff 'https://{my-workspace}.cerby.com/api/v1/collections?page[size]=3' \
--header 'x-api-key: {api-key}'

GET /api/v1/collections?page[size]=3 HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {api-key}

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://{my-workspace}.cerby.com/api/v1/collections?page[size]=3");
xhr.setRequestHeader("x-api-key", "{api-key}");

xhr.send();

import http.client

conn = http.client.HTTPSConnection("{my-workspace}.cerby.com")
payload = ''
headers = {
  'x-api-key': '{api-key}'
}
conn.request("GET", "/api/v1/collections?page%5Bsize%5D=3", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The following table describes the query parameters of a request:

Parameter	Required	Description
`page[number]` number	false	The page number to retrieve in the paginated result set. The default value is 1.
`page[size]` number	false	The number of items to return per page. The default value is 25.

Response

See an example of the response in the JSON tab.

{
    "data": [
        {
            "attributes": {
                "createdAt": "2024-07-12T23:10:27+00:00",
                "createdBy": "1cc381f7-1234-1234-ac7b-ae3cd6d1abcd",
                "meta": {},
                "name": "Employee",
                "roles": [
                    "collection_owner"
                ],
                "status": "enabled",
                "updatedAt": "2024-07-12T23:10:27+00:00",
                "updatedBy": "1cc381f7-1234-1234-ac7b-ae3cd6d1abcd"
            },
            "id": "2e376b17-1234-1234-8f72-4bb7d931abcd",
            "type": "collections"
        },
        {
            "attributes": {
                "createdAt": "2024-07-12T23:10:57+00:00",
                "createdBy": "1cc381f7-1234-1234-ac7b-ae3cd6d1abcd",
                "meta": {},
                "name": "Employee",
                "roles": [
                    "collection_owner"
                ],
                "status": "enabled",
                "updatedAt": "2024-07-12T23:10:58+00:00",
                "updatedBy": "1cc381f7-1234-1234-ac7b-ae3cd6d1abcd"
            },
            "id": "f4e74ed1-1234-1234-b29e-253e3f42abcd",
            "type": "collections"
        },
        {
            "attributes": {
                "createdAt": "2024-07-09T02:30:52+00:00",
                "createdBy": "1cc381f7-1234-1234-ac7b-ae3cd6d1abcd",
                "meta": {},
                "name": "Employee (2)",
                "roles": [
                    "collection_owner"
                ],
                "status": "enabled",
                "updatedAt": "2024-07-09T02:30:53+00:00",
                "updatedBy": "1cc381f7-1234-1234-ac7b-ae3cd6d1abcd"
            },
            "id": "7a089968-35d2-461a-9adc-01600e0cdf8d",
            "type": "collections"
        }
    ],
    "links": {
        "next": "/api/v1/collections?page%5Bnumber%5D=2&page%5Bsize%5D=3",
        "self": "/api/v1/collections?page%5Bnumber%5D=1&page%5Bsize%5D=3"
    },
    "meta": {
        "page": {
            "maxSize": 100,
            "total": 6
        }
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The JSON array with the collection objects requested on the specified page.	Collection schema Links object Meta object
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

Retrieve collection by ID

With a GET request to the collections/{id} endpoint, you can retrieve the information of a collection by providing its ID.

Path parameters

The following is an example of a request to the endpoint:

https://{my-workspace}.cerby.com/api/v1/collections/989165cc-112c-4112-a877-e047ffe9abcd

curl --location 'https://{my-workspace}.cerby.com/api/v1/collections/989165cc-112c-4112-a877-e047ffe9abcd' \
--header 'x-api-key: {api-key}'

GET /api/v1/collections/{id} HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {api-key}

// WARNING: For GET requests, body is set to null by browsers.

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://{my-workspace}.cerby.com/api/v1/collections/989165cc-112c-4112-a877-e047ffe9abcd");
xhr.setRequestHeader("x-api-key", "{api-key}");

xhr.send();

import http.client

conn = http.client.HTTPSConnection("{my-workspace}.cerby.com")
payload = ''
headers = {
  'x-api-key': '{api-key}'
}
conn.request("GET", "/api/v1/collections/989165cc-112c-4112-a877-e047ffe9abcd", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The following table describes the path parameters of a request:

Parameter	Required	Description
`id` string	true	The unique identifier of the collection.

Response

See an example of the response in the JSON tab.

{
    "data": {
        "attributes": {
            "createdAt": "2024-07-12T23:10:27+00:00",
            "createdBy": "989165cc-112c-4112-a877-e047ffe9abcd",
            "meta": {},
            "name": "Employee",
            "roles": [
                "collection_owner"
            ],
            "status": "enabled",
            "updatedAt": "2024-07-12T23:10:27+00:00",
            "updatedBy": "989165cc-112c-4112-a877-e047ffe9abcd"
        },
        "id": "989165cc-112c-4112-a877-e047ffe9abcd",
        "type": "collections"
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The requested collection JSON object.	Collection schema
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

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.

The user schema

See an example of the user schema in the JSON tab.

{  
    "attributes": {  
        "createdAt": "2024-01-04T15:36:54+00:00",  
        "email": "rose@poe.com",  
        "firstName": "Rose",  
        "isGuest": false,  
        "lastName": "Poe",  
        "role": "app_user",  
        "status": "live",  
        "updatedAt": "2024-07-08T19:30:56+00:00"  
    },  
    "id": "1234c85b-1234-1234-1234-7c886800abcd",  
    "type": "user"  
}

The following table describes the attributes of a user object:

Attribute		Description
`attributes` object		The attributes of the user.
	`createdAt` string	The date when the user was created in the ISO 8610 format.
	`email` string	The email of the user.
	`firstName` string	The first name of the user.
	`isGuest` boolean	The boolean value that indicates whether the user is a guest user. `True`, the user is a guest user; `false`, the user is not a guest user.
	`lastName` string	The last name of the user.
	`role` string	The workspace role of the user. The possible values are: `workspace_owner`, `workspace_super_admin`, `workspace_guest_admin`, `workspace_login_only`, `workspace_guest_user`
	`status` string	The status of the user in the workspace. The possible values are: `live` for active users, `pending` for users who have been provisioned or invited but have not logged in to the workspace or set up their user account, and `disabled` for users removed from the workspace.
`id` string		The unique identifier of the user.
`type` string		The resource type is always “user.”

List users

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

Query parameters

The following is an example of a request to the endpoint.

https://{my-workspace}.cerby.com/api/v1/users?page[size]=3

curl --location --globoff 'https://{my-workspace}.cerby.com/api/v1/users?page[size]=3' \
--header 'x-api-key: {api-key}'

GET /api/v1/users?page[size]=3 HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {api-key}

// WARNING: For GET requests, body is set to null by browsers.

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://{my-workspace}.cerby.com/api/v1/users?page[size]=3");
xhr.setRequestHeader("x-api-key", "{api-key}");

xhr.send();

import http.client

conn = http.client.HTTPSConnection("{my-workspace}.cerby.com")
payload = ''
headers = {
  'x-api-key': '{api-key}'
}
conn.request("GET", "/api/v1/users?page%5Bsize%5D=3", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The following table describes the query parameters of a request:

Parameter	Required	Description
`page[number]` integer	false	The page number to retrieve in a paginated list. The default and minimum value is 1.
`page[size]` integer	false	The number of items to display per page. The default value is 25; the maximum is 100.

Response

See an example of the response in the JSON tab.

{
    "data": [
        {
            "attributes": {
                "createdAt": "2024-01-04T15:36:54+00:00",
                "email": "joe@doe.com",
                "firstName": "Joe",
                "isGuest": false,
                "lastName": "Doe",
                "role": "app_user",
                "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": "kevin@example.com",
                "firstName": "Kevin",
                "isGuest": false,
                "lastName": "Example",
                "role": "workspace_super_admin",
                "status": "live",
                "updatedAt": "2024-09-24T18:41:23+00:00"
            },
            "id": "1234a545-1234-1234-1234-2f75c9eeabcd",
            "type": "user"
        },
        {
            "attributes": {
                "createdAt": "2021-10-19T17:58:43+00:00",
                "email": "rose@poe.com",
                "firstName": "Rose",
                "isGuest": false,
                "lastName": "Poe",
                "role": "app_user",
                "status": "live",
                "updatedAt": "2024-03-25T15:17:41+00:00"
            },
            "id": "12343fbc-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
        }
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The JSON array with the user objects requested on the specified page.	User schema Links object Meta object
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

Retrieve user by ID

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

Path parameters

The following is an example of a request to the endpoint:

https://{my-workspace}.cerby.com/api/v1/users/2e376b17-1234-1234-8f72-4bb7d931abcd

curl --location 'https://{my-workspace}.cerby.com/api/v1/users/2e376b17-1234-1234-8f72-4bb7d931abcd' \
--header 'x-api-key: {api-key}'

GET /api/v1/users/2e376b17-1234-1234-8f72-4bb7d931abcd HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {api-key}

// WARNING: For GET requests, body is set to null by browsers.

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://{my-workspace}.cerby.com/api/v1/users/2e376b17-1234-1234-8f72-4bb7d931abcd");
xhr.setRequestHeader("x-api-key", "{api-key}");

xhr.send();

import http.client

conn = http.client.HTTPSConnection("{my-workspace}.cerby.com")
payload = ''
headers = {
  'x-api-key': '{api-key}'
}
conn.request("GET", "/api/v1/users/2e376b17-1234-1234-8f72-4bb7d931abcd", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The following table describes the path parameters of a request:

Parameter	Required	Description
`id` string	true	The unique identifier of the user.

Response

See an example of the response in the JSON tab.

{
    "data": {
        "attributes": {
            "createdAt": "2024-01-04T15:36:54+00:00",
            "email": "joe@doe.com",
            "firstName": "Joe",
            "isGuest": false,
            "lastName": "Doe",
            "role": "app_user",
            "status": "live",
            "updatedAt": "2024-07-08T19:30:56+00:00"
        },
        "id": "2e376b17-1234-1234-8f72-4bb7d931abcd",
        "type": "user"
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The requested user JSON object.	User schema
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

Teams

In Cerby, teams are groups of users created to facilitate sharing items, updating roles on items, and provisioning user accounts in seat-based and paid social apps. A team object contains information about the team name, the team type, and the workspace ID.

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

Create a group assignment in your identity provider (IdP), such as Okta and Azure AD, to automatically create a team in Cerby via SCIM.
Create a self-managed team in Cerby with workspace users.

With the Cerby API, you can retrieve all teams or specific teams by providing their ID. To learn more about teams, refer to the Teams article collection on the Cerby Help Center.

The team schema

See an example of the team schema in the JSON tab.

{
    "attributes": {
        "createdAt": "2024-08-06T01:18:45+00:00",
        "name": "123abc",
        "type": "user_managed",
        "updatedAt": "2024-08-06T01:18:45+00:00"
        "workspaceId": "5aab889c-1234-4164-87b0-e07e57c12345"
    },
    "id": "c771bdcc-abcd-1234-a174-a3e032641234",
    "type": "team"
}

The following table describes the attributes of a team object:

Attribute		Description
`attributes` object		The attributes of the collection.
	`createdAt` string	The date when the team was created in the ISO 8610 format.
	`name` string	The name of the team.
	`type` string	The type of team according to how it was created. The possible values are: `scim_managed` and `user_managed`.
	`updatedAt` string	The date when the team was last updated in the ISO 8610 format.
	`workspaceId` string	The ID of the workspace where the team was created.
`id` string		The unique identifier of the team.
`type` string		The item type is always "team."

List teams

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

Query parameters

The following is an example of a request to the endpoint:

https://{my-workspace}.cerby.com/api/v1/teams?page[size]=3&page[number]=10

curl --location --globoff 'https://{my-workspace}.cerby.com/api/v1/teams?page[size]=3&page[number]=10' \
--header 'x-api-key: {api-key}'

GET /api/v1/teams?page[size]=3&page[number]=10 HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {api-key}

// WARNING: For GET requests, body is set to null by browsers.

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://{my-workspace}.cerby.com/api/v1/teams?page[size]=3&page[number]=10");
xhr.setRequestHeader("x-api-key", "xD8Fdzh9RKTvOQgUNqtkSCBEJ5iIPKsz");

xhr.send();

import requests

url = "https://{my-workspace}.cerby.com/api/v1/teams?page[size]=3&page[number]=10"

payload = {}
headers = {
  'x-api-key': '{api-key}'
}

response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)

The following table describes the query parameters of a request:

Parameter	Required	Description
`page[number]` integer	false	The page number to retrieve in a paginated list. The default and minimum value is 1.
`page[size]` integer	false	The number of items to display per page. The default value is 25; the maximum is 100.

Response

See an example of the response in the JSON tab.

{
    "data": [
        {
            "attributes": {
                "createdAt": "2024-08-06T01:18:45+00:00",
                "name": "acme",
                "type": "user_managed",
                "updatedAt": "2024-08-06T01:18:45+00:00",
                "workspaceId": "1234589c-abcd-abcd-87b0-e07e57c12345"
            },
            "id": "5aab889c-1234-4164-87b0-e07e57c12345",
            "type": "team"
        },
        {
            "attributes": {
                "createdAt": "2024-08-06T01:18:45+00:00",
                "name": "general",
                "type": "user_managed",
                "updatedAt": "2024-08-06T01:18:45+00:00",
                "workspaceId": "1234589c-abcd-abcd-87b0-e07e57c12345"
            },
            "id": "5aab889c-1234-4164-87b0-e07e57c12345",
            "type": "team"
        },
        {
            "attributes": {
                "createdAt": "2024-08-06T01:18:45+00:00",
                "name": "technical writing",
                "type": "user_managed",
                "updatedAt": "2024-08-06T01:18:45+00:00",
                "workspaceId": "1234589c-abcd-abcd-87b0-e07e57c12345"
            },
            "id": "5aab889c-1234-4164-87b0-e07e57c12345",
            "type": "team"
        }
    ],
    "links": {
        "next": "/api/v1/teams?page%5Bnumber%5D=11&page%5Bsize%5D=3",
        "previous": "/api/v1/teams?page%5Bnumber%5D=9&page%5Bsize%5D=3",
        "self": "/api/v1/teams?page%5Bnumber%5D=10&page%5Bsize%5D=3"
    },
    "meta": {
        "page": {
            "maxSize": 100,
            "total": 135
        }
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The JSON array with the team objects requested on the specified page.	Team schema Links object Meta object
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

Retrieve team by ID

With a GET request to the teams/{id} endpoint, you can retrieve the information of a team by providing its ID.

Path parameters

The following is an example of a request to the endpoint:

https://{my-workspace}.cerby.com/api/v1/teams/5aab889c-1234-4164-87b0-e07e57c12345

curl --location 'https://{my-workspace}.cerby.com/api/v1/teams/5aab889c-1234-4164-87b0-e07e57c12345' \
--header 'x-api-key: {api-key}'

GET /api/v1/teams/5aab889c-1234-4164-87b0-e07e57c12345 HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {api-key}

// WARNING: For GET requests, body is set to null by browsers.

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://{my-workspace}.cerby.com/api/v1/teams/5aab889c-1234-4164-87b0-e07e57c12345");
xhr.setRequestHeader("x-api-key", "{api-key}");

xhr.send();

import http.client

conn = http.client.HTTPSConnection("{my-workspace}.cerby.com")
payload = ''
headers = {
  'x-api-key': '{api-key}'
}
conn.request("GET", "/api/v1/teams/5aab889c-1234-4164-87b0-e07e57c12345", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The following table describes the path parameters of a request:

Parameter	Required	Description
`id` string	true	The unique identifier of the team.

Response

See an example of the response in the JSON tab.

{
    "data": {
        "attributes": {
            "createdAt": "2024-08-06T01:18:45+00:00",
            "name": "Admins",
            "type": "user_managed",
            "updatedAt": "2024-08-06T01:18:45+00:00",
            "workspaceId": "1234589c-abcd-abcd-87b0-e07e57c12345"
        },
        "id": "5aab889c-1234-4164-87b0-e07e57c12345",
        "type": "team"
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The requested team JSON object.	Team schema
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

Integrations

In Cerby, integrations are the connections between seat-based and paid social apps with a Cerby workspace. The goal is to enable companies to centralize in Cerby the lifecycle management of user accounts within these apps, characterized by having collaboration spaces (workspaces, teams, or dashboards) and individual seats or licenses for user access. The connection is based on API requests or automated jobs.

Depending on the API endpoint, you can retrieve any of the following two objects from an integration:

integration object: Contains information about the app connected to Cerby, the date when the integration was created, the user who created and last updated the account, and other relevant attributes.
entitlement object: Contains information about the available user roles in the app or the roles assigned to a user. In the second case, the entitlement object is an attribute of a user object.

A business-hub object is created in Cerby when you connect an integration through the Cerby web app, whereas an entitlement object is created in response to a specific request you make to the Cerby API.

With the Cerby API, you can retrieve specific integrations by providing their ID, the available entitlements, all the users in an integrations, and specific users in an integration by providing their ID. Also, you can update the entitlements of a user in an integration.

To learn more about integrations, refer to the Integrations article collection on the Cerby Help Center.

The integration schema

See a sample of the integration schema in the JSON tab.

{
    "data": {
        "attributes": {
            "application": "youtube_tenant",
            "createdAt": "2024-03-20T20:11:13+00:00",
            "createdBy": "1ab381d7-abcd-dcab-ac7b-343cd6d12345",
            "label": "Youtube Acme",
            "updatedAt": "2024-03-25T15:20:09+00:00",
            "workspace": "acme"
        },
        "id": "1234422e-abcd-4ee0-3322-54eecbcbab00",
        "type": "account"
    }
}

The following table describes the attributes of an integration object:

Attribute		Description
`attributes` object		The attributes of the integration.
	`application` string	The service provider or application associated with the integration.
	`createdAt` string	The date when the integration was created in the ISO 8610 format.
	`createdBy` string	The ID of the user who created the integration.
	`label` string	The name or label of the integration.
	`updatedAt` string	The date when the integration was last updated in the ISO 8610 format.
	`workspace` string	The name of the workspace to which the integration is connected.
`id` string		The unique identifier of the integration.
`type` string		The type is always “account.”

The entitlement schema

See a sample of the entitlement schema in the JSON tab.

{
    "attributes": {
        "group": "primary",
        "key": "VIEWER_LIMITED",
        "label": "YOUTUBE_TENANT_VIEWER_LIMITED_DESC",
        "value": "VIEWER_LIMITED"
    },
    "id": "VIEWER_LIMITED",
    "type": "entitlement"
}

The following table describes the attributes of an entitlement object:

Attribute		Description
`attributes` object		The attributes of the entitlement.
	`group` string	The group of the entitlement. The possible values are: primary, for `primary` roles like admin or employee, and `secondary`, for secondary roles like finance or analyst.
	`key` string	The key identifier of the entitlement.
	`label` string	The name or label of the entitlement.
	`value` string	The value assigned to the entitlement.
`id` string		The unique identifier of the entitlement.
`type` string		The type is always “entitlement.”

The integration user schema

See a sample of the integration user schema in the JSON tab.

{
    "attributes": {
        "email": "joe@doe.com",
        "entitlements": [
        {
            "attributes": {
                "group": "primary",
                "key": "VIEWER_LIMITED",
                "label": "TENANT_VIEWER_LIMITED_DESC",
                "value": "VIEWER_LIMITED"
            },
            "id": "VIEWER_LIMITED",
            "type": "entitlement"
        }
        ],
        "firstName": "Joe",
        "isGuest": false,
        "lastName": "Doe",
        "role": "account_collaborator",
        "status": "live"
    },
    "id": "abc93f7e-1234-42e0-abcd-fca12345f0a6",
    "type": "user"
}

The following table describes the attributes of an integration user object:

Attribute		Description
`attributes` object		The attributes of the user.
	`email` string	The email of the user.
	`entitlements` array	The array of all entitlement objects assigned to the user.
	`firstName` string	The first name of the user.
	`isGuest` boolean	The boolean value that indicates whether the user is a guest user with access to the integration. `True`, the user is a guest user; `false`, the user is not a guest user.
	`lastName` string	The last name of the user.
	`role` string	The role of the user on the integration account. The possible values are: `owner` and `collaborator`.
	`status` string	The status of the user in the integration. The possible values are: `started`, `created`, `finished`, `error`, `running`, and `retrying`.
`id` string		The unique identifier of the user.
`type` string		The type is always "user."

Retrieve integration by ID

With a GET request to the integrations/{id} endpoint, you can retrieve the information of an integration by providing its ID.

Path parameters

The following is an example of a request to the endpoint.

https://{my-workspace}.cerby.com/api/v1/integrations/a427011c-abcd-1234-8393-43abcbcb1234

curl --location 'https://{my-workspace}.cerby.com/api/v1/integrations/a427011c-abcd-1234-8393-43abcbcb1234' \
--header 'x-api-key: {api-key}'

GET /api/v1/integrations/a427011c-abcd-1234-8393-43abcbcb1234 HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {api-key}

// WARNING: For GET requests, body is set to null by browsers.

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://{my-workspace}.cerby.com/api/v1/integrations/a427011c-abcd-1234-8393-43abcbcb1234");
xhr.setRequestHeader("x-api-key", "{api-key}");

xhr.send();

import http.client

conn = http.client.HTTPSConnection("{my-workspace}.cerby.com")
payload = ''
headers = {
  'x-api-key': '{api-key}'
}
conn.request("GET", "/api/v1/integrations/a427011c-abcd-1234-8393-43abcbcb1234", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The following table describes the path parameters of a request:

Parameter	Required	Description
`id` string	true	The unique identifier of the integration.

Response

See an example of the response in the JSON tab.

{
    "data": {
        "attributes": {
            "application": "youtube_tenant",
            "createdAt": "2024-03-20T20:11:13+00:00",
            "createdBy": "1ab381d7-abcd-dcab-ac7b-343cd6d12345",
            "label": "Youtube acme",
            "updatedAt": "2024-03-25T15:20:09+00:00",
            "workspace": "acme"
        },
        "id": "a427011c-abcd-1234-8393-43abcbcb1234",
        "type": "account"
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The requested integration JSON object.	Integration schema Links object Meta object
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

List integration entitlements

With a GET request to the integrations/{id}/entitlements endpoint, you can retrieve a list of the entitlements (roles) available for assignment in an integration by providing the integration ID.

Path parameters

The following is an example of a request to the endpoint.

https://{my-workspace}.cerby.com/api/v1/integrations/a427011c-abcd-1234-8393-43abcbcb1234/entitlements

curl --location 'https://{my-workspace}.cerby.com/api/v1/integrations/a427011c-abcd-1234-8393-43abcbcb1234/entitlements' \
--header 'x-api-key: {api-key}' \
--data ''

GET /api/v1/integrations/a427011c-abcd-1234-8393-43abcbcb1234/entitlements HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {api-key}

// WARNING: For GET requests, body is set to null by browsers.
var data = "";

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://{my-workspace}.cerby.com/api/v1/integrations/a427011c-abcd-1234-8393-43abcbcb1234/entitlements");
xhr.setRequestHeader("x-api-key", "{api-key}");

xhr.send(data);

import http.client

conn = http.client.HTTPSConnection("{my-workspace}.cerby.com")
payload = ''
headers = {
  'x-api-key': '{api-key}'
}
conn.request("GET", "/api/v1/integrations/a427011c-abcd-1234-8393-43abcbcb1234/entitlements", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The following table describes the path parameters of a request:

Parameter	Required	Description
`id` string	true	The unique identifier of the integration.

Response

See an example of the response in the JSON tab.

{
    "data": [
        {
            "attributes": {
                "group": "primary",
                "key": "MANAGER",
                "label": "YOUTUBE_TENANT_MANAGER_DESC",
                "value": "MANAGER"
            },
            "id": "MANAGER",
            "type": "entitlement"
        },
        {
            "attributes": {
                "group": "primary",
                "key": "EDITOR",
                "label": "YOUTUBE_TENANT_EDITOR_DESC",
                "value": "EDITOR"
            },
            "id": "EDITOR",
            "type": "entitlement"
        },
        {
            "attributes": {
                "group": "primary",
                "key": "VIEWER_LIMITED",
                "label": "YOUTUBE1-Q_TENANT_VIEWER_LIMITED_DESC",
                "value": "VIEWER_LIMITED"
            },
            "id": "VIEWER_LIMITED",
            "type": "entitlement"
        }
    ]
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The JSON array with the entitlement objects requested.	Entitlement schema
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

Update a user’s entitlements in an integration

With a PATCH request to the integrations/{id}/users/{userId} endpoint, you can update a user’s entitlements in an integration by providing the user and integration IDs.

Path parameters

See the JSON tab to see an example of a request URL.

https://{my-workspace}.cerby.com/api/v1/integrations/76b00adb-1234-abcd-8888-c15a0fa12345/users/a4393f7e-abcd-1234-b00b-fca770123456

The following table describes the path parameters of a request:

Parameter	Required	Description
`id` string	true	The unique identifier of the integration.
`userId` string	true	The unique identifier of the user to update.

Body

The following is an example of a request to the endpoint:

{
    "data": {
        "type": "update_user_entitlement",
        "attributes": {
            "entitlements": [
                {
                    "id": "VIEWER"
                }
            ]
        }
    }
}

curl --location --request PATCH 'https://{my-workspace}.cerby.com/api/v1/integrations/76b00adb-1234-abcd-8888-c15a0fa12345/users/a4393f7e-abcd-1234-b00b-fca770123456' \
--header 'x-api-key: {api-key}' \
--header 'Content-Type: application/json' \
--data '{
    "data": {
        "type": "update_user_entitlement",
        "attributes": {
            "entitlements": [
                {
                    "id": "VIEWER"
                }
            ]
        }
    }
}'

PATCH /api/v1/integrations/76b00adb-1234-abcd-8888-c15a0fa12345/users/a4393f7e-abcd-1234-b00b-fca770123456 HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key:{api-key}
Content-Type: application/json
Content-Length: 215

{
    "data": {
        "type": "update_user_entitlement",
        "attributes": {
            "entitlements": [
                {
                    "id": "VIEWER"
                }
            ]
        }
    }
}

var data = JSON.stringify({
  "data": {
    "type": "update_user_entitlement",
    "attributes": {
      "entitlements": [
        {
          "id": "VIEWER"
        }
      ]
    }
  }
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("PATCH", "https://{my-workspace}.cerby.com/api/v1/integrations/76b00adb-1234-abcd-8888-c15a0fa12345/users/a4393f7e-abcd-1234-b00b-fca770123456");
xhr.setRequestHeader("x-api-key", "{api-key}");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);

import http.client
import json

conn = http.client.HTTPSConnection("{my-workspace}.cerby.com")
payload = json.dumps({
  "data": {
    "type": "update_user_entitlement",
    "attributes": {
      "entitlements": [
        {
          "id": "VIEWER"
        }
      ]
    }
  }
})
headers = {
  'x-api-key': ‘{api-key}’,
  'Content-Type': 'application/json'
}
conn.request("PATCH", "/api/v1/integrations/76b00adb-1234-abcd-8888-c15a0fa12345/users/a4393f7e-abcd-1234-b00b-fca770123456", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The following table describes the object attributes you must send in the body of your request:

Parameter				Required	Description
`data` object				true	The attributes of the object.
	`type` object			true	The action type in the request. The available action is: `update_user_entitlement`
	`attributes` object			true	The attributes of the entitlements.
		`entitlements` array		true	The array with the entitlements to be assigned to the user.
			`id` string	true	The ID of the entitlement to be assigned to the user. The available entitlements depend on the integration.

Response

See an example of the response in the JSON tab.

{
    "data": {
        "attributes": {
            "status": "created"
        },
        "id": "add12344-6550-abad-67c9-315e734923a5",
        "type": "job"
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The JSON array with the entitlement objects requested.	Entitlement schema with the `created` status
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

Retrieve user of an integration

With a GET request to the integrations/{id}/users/{userId} endpoint, you can retrieve a user of an integration by providing the user and integration IDs.

Path parameters

The following is an example of a request to the endpoint.

https://{my-workspace}.cerby.com/api/v1/integrations/76b00adb-1234-1bcd-8868-b04a0fa8baa8/users/a4393f7e-1234-abcd-b23b-fca770912345

curl --location 'https://{my-workspace}.cerby.com/api/v1/integrations/76b00adb-1234-1bcd-8868-b04a0fa8baa8/users/a4393f7e-1234-abcd-b23b-fca770912345' \
--header 'x-api-key: {api-key}' \
--data ''

GET /api/v1/integrations/76b00adb-1234-1bcd-8868-b04a0fa8baa8/users/a4393f7e-1234-abcd-b23b-fca770912345 HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {api-key}

// WARNING: For GET requests, body is set to null by browsers.
var data = "";

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://{my-workspace}.cerby.com/api/v1/integrations/76b00adb-1234-1bcd-8868-b04a0fa8baa8/users/a4393f7e-1234-abcd-b23b-fca770912345");
xhr.setRequestHeader("x-api-key", "{api-key}");

xhr.send(data);

import http.client

conn = http.client.HTTPSConnection("{my-workspace}.cerby.com")
payload = ''
headers = {
  'x-api-key': '{api-key}'
}
conn.request("GET", "/api/v1/integrations/76b00adb-1234-1bcd-8868-b04a0fa8baa8/users/a4393f7e-1234-abcd-b23b-fca770912345", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The following table describes the path parameters of a request:

Parameter	Required	Description
`id` string	true	The unique identifier of the integration.
`userId` string	true	The unique identifier of the user to retrieve.

Response

See an example of the response in the JSON tab.

{
    "data": {
        "attributes": {
            "email": "joe@doe.com",
            "entitlements": [
                {
                    "attributes": {
                        "group": "primary",
                        "key": "EMPLOYEE",
                        "label": "PINTEREST_BUSINESS_EMPLOYEE_DESC",
                        "value": "EMPLOYEE"
                    },
                    "id": "EMPLOYEE",
                    "type": "entitlement"
                }
            ],
            "firstName": "Joe",
            "isGuest": false,
            "lastName": "Doe",
            "role": "it_admin",
            "status": "live"
        },
        "id": "a4393f7e-1234-abcd-b23b-fca770912345",
        "type": "user"
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The requested integration user JSON objects.	Integration user schema
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

List users of an integration

With a GET request to the integrations/{id}/users endpoint, you can retrieve the list of users of an integration by providing the integration ID.

Path parameters

The following is an example of a request to the endpoint.

https://{my-workspace}.cerby.com/api/v1/integrations/d538422e-1234-abcd-8393-54eecbcb4a07/users

curl --location 'https://{my-workspace}.cerby.com/api/v1/integrations/d538422e-1234-abcd-8393-54eecbcb4a07/users' \
--header 'x-api-key: {api-key}' \
--data ''

GET /api/v1/integrations/d538422e-1234-abcd-8393-54eecbcb4a07/users HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {api-key}

// WARNING: For GET requests, body is set to null by browsers.
var data = "";

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://{my-workspace}.cerby.com/api/v1/integrations/d538422e-1234-abcd-8393-54eecbcb4a07/users");
xhr.setRequestHeader("x-api-key", "{api-key}");

xhr.send(data);

import http.client

conn = http.client.HTTPSConnection("{my-workspace}.cerby.com")
payload = ''
headers = {
  'x-api-key': '{api-key}'
}
conn.request("GET", "/api/v1/integrations/d538422e-1234-abcd-8393-54eecbcb4a07/users", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The following table describes the path parameters of a request:

Parameter	Required	Description
`id` string	true	The unique identifier of the integration.

Query parameters

The following table describes the query parameters of a request:

Parameter	Required	Description
`page[number]` integer	false	The page number to retrieve in a paginated list. The default and minimum value is 1.
`page[size]` integer	false	The number of items to display per page. The default value is 25; the maximum is 100.

Response

See an example of the response in the JSON tab.

{
    "data": [
        {
            "attributes": {
                "email": "jane@user.com",
                "entitlements": [
                    {
                        "attributes": {
                            "group": "primary",
                            "key": "VIEWER_LIMITED",
                            "label": "TENANT_VIEWER_LIMITED_DESC",
                            "value": "VIEWER_LIMITED"
                        },
                        "id": "VIEWER_LIMITED",
                        "type": "entitlement"
                    }
                ],
                "firstName": "Jane",
                "isGuest": false,
                "lastName": "User",
                "role": "account_collaborator",
                "status": "live"
            },
            "id": "04393f7e-2244-1234-abcd-fca770123456",
            "type": "user"
        },
        {
            "attributes": {
                "email": "joe@doe.com",
                "entitlements": [
                    {
                        "attributes": {
                            "group": "primary",
                            "key": "EDITOR_LIMITED",
                            "label": "YOUTUBE_TENANT_EDITOR_LIMITED_DESC",
                            "value": "EDITOR_LIMITED"
                        },
                        "id": "EDITOR_LIMITED",
                        "type": "entitlement"
                    }
                ],
                "firstName": "Joe",
                "isGuest": false,
                "lastName": "Doe",
                "role": "account_owner",
                "status": "live"
            },
            "id": "0c9dabcb-1234-abcd-1234-1234c8003555",
            "type": "user"
        }
    ],
    "links": {
        "next": null,
        "previous": null,
        "self": "/api/v1/integrations/d538422e-b135-4ee0-8393-54eecbcb4a07/users?page%5Bnumber%5D=1&page%5Bsize%5D=20"
    },
    "meta": {
        "page": {
            "maxSize": 100,
            "total": 4
        }
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The JSON array with the integration user objects requested on the specified page.	Integration user schema
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

Invite user to an integration

With a POST request to the integrations/{id}/users endpoint, you can invite a user to an integration by providing the integration ID.

Path parameters

See an example of a request URL in the JSON tab.

https://{my-workspace}.cerby.com/api/v1/integrations/d538422e-1234-4ee0-8393-54eecbcb4a07/users

The following table describes the path parameters of a request:

Parameter	Required	Description
`id` string	true	The unique identifier of the integration.

Body

The following is an example of a request to the endpoint:

{
    "data":{
        "attributes":{
            "role": "account_owner",
            "entitlements": [
                {
                    "id": "VIEWER_LIMITED"
                }
            ],
            "userIds": [
                "1cc381f7-9c52-419f-ac7b-ae3cd6d148d4"
            ]
        },
        "type": "invite_tenant_users"
    }
}

curl --location 'https://{my-workspace}.cerby.com/api/v1/integrations/d538422e-1234-4ee0-8393-54eecbcb4a07/users' \
--header 'x-api-key: {api-key}' \
--header 'Content-Type: application/json' \
--data '{
    "data":{
        "attributes":{
            "role": "account_owner",
            "entitlements": [
                {
                    "id": "VIEWER_LIMITED"
                }
            ],
            "userIds": [
                "1cc381f7-9c52-419f-ac7b-ae3cd6d148d4"
            ]
        },
        "type": "invite_tenant_users"
    }
}'

POST /api/v1/integrations/d538422e-1234-4ee0-8393-54eecbcb4a07/users HTTP/1.1
Host:{my-workspace}.cerby.com
x-api-key:{api-key}
Content-Type: application/json
Content-Length: 341

{
    "data":{
        "attributes":{
            "role": "account_owner",
            "entitlements": [
                {
                    "id": "VIEWER_LIMITED"
                }
            ],
            "userIds": [
                "1cc381f7-9c52-419f-ac7b-ae3cd6d148d4"
            ]
        },
        "type": "invite_tenant_users"
    }
}

// WARNING: For POST requests, body is set to null by browsers.
var data = JSON.stringify({
  "data": {
    "attributes": {
      "role": "account_owner",
      "entitlements": [
        {
          "id": "VIEWER_LIMITED"
        }
      ],
      "userIds": [
        "1cc381f7-9c52-419f-ac7b-ae3cd6d148d4"
      ]
    },
    "type": "invite_tenant_users"
  }
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://{my-workspace}.cerby.com/api/v1/integrations/d538422e-1234-4ee0-8393-54eecbcb4a07/users");
xhr.setRequestHeader("x-api-key", "{api-key}");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);

import requests
import json

url = "https://{my-workspace}.cerby.com/api/v1/integrations/d538422e-1234-4ee0-8393-54eecbcb4a07/users"

payload = json.dumps({
  "data": {
    "attributes": {
      "role": "account_owner",
      "entitlements": [
        {
          "id": "VIEWER_LIMITED"
        }
      ],
      "userIds": [
        "1cc381f7-9c52-419f-ac7b-ae3cd6d148d4"
      ]
    },
    "type": "invite_tenant_users"
  }
})
headers = {
  'x-api-key': ‘{api-key}’,
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

The following table describes the object attributes you must send in the body of your request:

Parameter			Required	Description
`data` object			true	The attributes of the object.
	`attributes` object		true	The attributes of the entitlements.
		`role` string	true	The role to assign to the user on the integration. The possible values are: `account_owner` and `account_collaborator`.
		`entitlements` array	true	The array with the entitlements to assign to the user. The available entitlements depend on the integration.
		`id` string	true	The entitlement ID to be assigned to the user.
		`userIds` array	true	The array of user IDs to invite to the integration.
		`type` array	true	The job type is always `invite_tenant_users`.

Response

See an example of the response in the JSON tab.

{
    "data": {
        "attributes": {
            "status": "created"
        },
        "id": "43c65e54-07fb-48c1-90e4-498d91b0f8b9",
        "type": "job"
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The JSON array with the entitlement object requested.	Entitlement schema with the created status, meaning that the automated job was created
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

Remove user from an integration

With a DELETE request to the integrations/{id}/users/{userId} endpoint, you can remove a user from an integration by providing the integration and the user IDs.

Path parameters

The following is an example of a request to the endpoint:

https://{my-workspace}.cerby.com/api/v1/integrations/65b00abc-8737-4fec-8888-c15a0fa8baaa/users/abcdef7e-1144-42e0-b23b-fca12345f0ab

curl --location --request DELETE 'https://{my-workspace}.cerby.com/api/v1/integrations/65b00abc-8737-4fec-8888-c15a0fa8baaa/users/abcdef7e-1144-42e0-b23b-fca12345f0ab' \
--header 'x-api-key: {api-key}' \
--header 'Content-Type: application/json' \
}'

DELETE /api/v1/integrations/765b00abc-8737-4fec-8888-c15a0fa8baaa/users/abcdef7e-1144-42e0-b23b-fca12345f0ab HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {api-key}
Content-Type: application/json
Content-Length: 127

var data = "";

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://{my-workspace}.cerby.com/api/v1/integrations/65b00abc-8737-4fec-8888-c15a0fa8baaa/users/abcdef7e-1144-42e0-b23b-fca12345f0ab");
xhr.setRequestHeader("x-api-key", "{api-key}");

xhr.send(data);

import http.client

conn = http.client.HTTPSConnection("{my-workspace}.cerby.com")
payload = ''
headers = {
  'x-api-key': '{api-key}'
}
conn.request("DELETE", "/api/v1/integrations/65b00abc-8737-4fec-8888-c15a0fa8baaa/users/abcdef7e-1144-42e0-b23b-fca12345f0ab", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The following table describes the path parameters of a request:

Parameter	Required	Description
`id` string	true	The unique identifier of the integration.
`userId` string	true	The unique identifier of the user to be removed.

Response

See an example of the response in the JSON tab.

{
    "data": {
        "attributes": {
            "status": "created"
        },
        "id": "722fbd00-421f-4f7a-babc-b12348e2bb12",
        "type": "job"
    }
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The JSON array with the entitlement object requested.	Entitlement schema with the created status, meaning that the automated job was created
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors

Jobs

In Cerby, jobs are the automated workflows performed server-side by the Cerby bot either through API requests or interactions on a headless browser. The goal of these jobs is to protect user accounts and manage user access to seat-based and paid social apps. A job object contains information about the type of automation job, the provider, if it can be retried, the user who created the job, the job status, and other relevant attributes.

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

Trigger manually any of the following supported automated tasks for managed accounts through the Cerby web app:
- Update password
- Turn on or off two-factor authentication (2FA)
- Update email address
- Update phone number
- Check 2FA status
Trigger automatically, based on a workspace policy, any of the supported automated tasks for managed accounts.
Trigger manually any of the following supported automated tasks for integrations through the Cerby web app:
- Check for updates
- Invite a user
- Update a user’s role
- Remove a user
- Monitor partners
- Manage partner assets
Trigger automatically, based on a user deprovisioning event, the automated task to remove a user from an integration.
Trigger any of the supported automated tasks for integrations through the Cerby API.

With the Cerby API, you can retrieve specific jobs by providing their ID. To learn more about automated jobs or tasks, refer to the articles about accounts and integrations on the Cerby Help Center.

The job schema

See a sample of the job schema in the JSON tab.

{
     "attributes": {
         "account": {
             "entity": "account",
             "id": "123455cc-abcd-1234-abcd-e047ffe9abcd",
             "name": "Discord sync on August 29",
             "provider": "discord_tenant"
         },
         "canRetry": false,
         "createdAt": "2024-08-29T19:31:21.563000+00:00",
         "createdBy": {
             "id": "abcde0cc-abcd-1234-abcd-e047ffe12345",
             "name": "Joe Doe"
         },
         "errorDetails": {},
         "hasMoreDetails": false,
         "response": {},
         "status": "finished",
         "trigger": "manual",
         "updatedAt": "2024-08-29T19:31:22.750000+00:00",
         "workflowType": "proxy_account_roles_update"
     },
     "id": "a2c3b0cc-abcd-a09d-abcd-e047ffe91234",
     "type": "job"
 }

The following table describes the attributes of the job object:

Attribute			Description
`attributes` object			The attributes of the jobs.
	`account` object		The account object related to the job.
		`entity` string	The object entity type is always “account.”
		`id` string	The unique identifier of the account.
		`name` string	The name of the account.
		`provider` string	The service provider or application associated with the account.
	`canRetry` boolean		The boolean value that indicates whether the job can be retried. `True`, the job can be retried; `false`, the job cannot be retried.
	`createdAt` string		The date when the job was created in the ISO 8610 format.
	`createdBy` string		The user object related to the user who created the job.
		`id` string	The ID of the user who created the job.
		`name` string	The name of the user who created the job.
	`errorDetails` object		The error detail object related to the job.
		`errorType` string	The error type.
		`screenshotUrl` string	The URL of the screenshot showing where the error occurred.
		`userRequired` boolean	The boolean value that indicates whether user intervention is required to solve the error. `True`, the user is required; `false`, the user is not required.
	`hasMoreDetails` boolean		The boolean value that indicates whether the error has more details. `True`, the error has more details; `false`, the error has no error details.
	`payload` object		The payload object related to the job.
	`response` object		The response object of the job.
	`status` string		The status of the job. The possible values are: `started`, `created`, `finished`, `error`, `running`, and `retrying`.
	`trigger` string		The trigger of the job. The possible values are: `manual`, `workspace_policy`, `system, and user_deprovisioned.`
	`updatedAt` string		The date when the job was last updated in the ISO 8610 format.
	`workflowType` string		The type of workflow performed. The possible values for accounts are: `password_rotation`, `setup_mfa`, `disable_mfa`, `email_swap_in`, `phone_swap_in`, and `healthcheck_mfa`. The possible values for integrations are: `get_business`, `provide_access`, `update_access`, `revoke_access`, `get_native_partner_business`, `provide_native_partner_access`, and `revoke_native_partner_access`.
	`workspacePolicyEnforcementId` string		The unique identifier of the enforced workspace policy.
`id` string			The unique identifier of the collection.
`type` string			The item type is always “job.”

Retrieve job by ID

With a GET request to the jobs/{id} endpoint, you can retrieve the information of a job by providing its ID.

Path parameters

The following is an example of a request to the endpoint:

https://{my-workspace}.cerby.com/api/v1/jobs/a2c3b0cc-abcd-a09d-abcd-e047ffe91234

curl --location 'https://{my-workspace}.cerby.com/api/v1/jobs/a2c3b0cc-abcd-a09d-abcd-e047ffe91234' \
--header '{api-key}'

GET /api/v1/jobs/a2c3b0cc-abcd-a09d-abcd-e047ffe91234 HTTP/1.1
Host: {my-workspace}.cerby.com
x-api-key: {api-key}

// WARNING: For GET requests, body is set to null by browsers.

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://{my-workspace}.cerby.com/api/v1/jobs/a2c3b0cc-abcd-a09d-abcd-e047ffe91234");
xhr.setRequestHeader("x-api-key", "{api-key}");

xhr.send();

import http.client

conn = http.client.HTTPSConnection("{my-workspace}.cerby.com")
payload = ''
headers = {
  'x-api-key': '{api-key}'
}
conn.request("GET", "/api/v1/jobs/a2c3b0cc-abcd-a09d-abcd-e047ffe91234", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

The following table describes the path parameters of a request:

Parameter	Required	Description
`id` string	true	The unique identifier of the job.

Response

See an example of the response in the JSON tab.

{
    "data": {
        "attributes": {
            "account": {
                "entity": "account",
                "id": "123455cc-abcd-1234-abcd-e047ffe9abcd",
                "name": "Discord",
                "provider": "discord_tenant"
            },
            "canRetry": false,
            "createdAt": "2024-08-29T19:31:21.563000+00:00",
            "createdBy": {
                "id": "abcde0cc-abcd-1234-abcd-e047ffe12345",
                "name": "Joe Doe"
            },
            "errorDetails": {},
            "hasMoreDetails": false,
            "response": {},
            "status": "finished",
            "trigger": "manual",
            "updatedAt": "2024-08-29T19:31:22.750000+00:00",
            "workflowType": "proxy_account_roles_update"
        },
        "id": "a2c3b0cc-abcd-a09d-abcd-e047ffe91234",
        "type": "job"
    },
    "links": {
        "self": "/api/v1/jobs/a2c3b0cc-abcd-a09d-abcd-e047ffe91234"
    },
    "meta": {}
}

The following table describes the response status and messages:

Status	Response	Description	Schema
`200`	`OK`	The requested job JSON object.	Job schema Links object Meta object
`401`	`Unauthorized`	Unauthorized. The request requires user authentication.	Errors
`404`	`Not found`	Not found. The requested resource could not be found.	Errors