Cerby API Reference

Learn more about documenting APIs in GitBook.

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

• Vaults

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.

Important:

• If the API key is expired or does not have the correct scopes, the Cerby API returns a 401 error.

• Your API keys are sensitive resources because they grant access to the data you have saved in your workspace. Avoid sharing them in public repositories or client-side code.

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.

• PUT: Replaces an existing resource with the data provided in the request. For example, PUT /users/{id} to fully update a user’s details in your Cerby workspace.

• DELETE: Removes a resource from the server. For example, DELETE /users/{id} to permanently delete a user from your Cerby workspace.

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

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

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:

Important: The parameters in this section are not applicable to all endpoints. Refer to the documentation for each specific endpoint to see which parameters apply.

• 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[secretType]: The type of secret you want to retrieve from an account. The only possible value is: password.

  • 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.

Header

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, PUT, 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": "[e-mail]"
         },
         "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 Response status codes 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

  • Links object

  • Meta object

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

{
    "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

{
  "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

{
  "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.
201	Created	The request was successful, and a resource was created in Cerby.
204	No content	The request was successful.
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.
409	Conflict	The request conflicts with the current state of the resource.
429	Too many requests	The user has sent too many requests in a given amount of time ("rate limiting"). Retry in five minutes.

View OpenAPI spec