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.

Important: You can only retrieve secrets to which you have the Owner role. Your permissions are determined by your API key based on Cerby’s RBAC system.

List secrets

get

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

Important: The API scope required to use this endpoint is: Read secrets.

Query parameters

page[number]integer · min: 1Optional

The page number to retrieve in the paginated result set.

Default: 1

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

The number of items to return per page.

Default: 25

Responses

200

OK - The JSON array with the secret objects requested on the specified page.

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

get

/secrets

HTTPcURLJavaScriptPython

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

{
  "data": [
    {
      "attributes": {
        "category": "text",
        "createdAt": "2023-07-26T23:33:03.860000+00:00",
        "createdBy": "123456a7-1234-419f-123a-ae3cd6d12345",
        "eventName": "create",
        "expiresAt": null,
        "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": {
        "category": "text",
        "createdAt": "2023-07-27T19:06:06.860000+00:00",
        "createdBy": "123456a7-1234-419f-123a-ae3cd6d12345",
        "eventName": "create",
        "expiresAt": null,
        "requiresIdentityChallenge": false,
        "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": {
        "category": "text",
        "createdAt": "2023-10-04T02:00:06.860000+00:00",
        "createdBy": "123456a7-1234-419f-123a-ae3cd6d12345",
        "eventName": "create",
        "expiresAt": null,
        "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
    }
  }
}

Create a secret

post

With a POST request to the /secrets endpoint, you can create a secret in your workspace.

Important: The API scopes required to use this endpoint are Read secrets and Write secrets.

Body

application/json

Responses

201

Created - The new secret JSON object.

application/json

400

Bad request - The server could not interpret the request due to invalid syntax or missing parameters. Review your request and correct it.

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

post

/secrets

HTTPcURLJavaScriptPython

POST /api/v1/secrets HTTP/1.1
Host: my-workspace.cerby.com
Content-Type: application/json
Accept: */*
Content-Length: 219

{
  "data": {
    "attributes": {
      "vaultId": "c123a836-abcd-473f-bbba-6e0113716285",
      "title": "Test public secret created",
      "requiresIdentityChallenge": false,
      "body": {
        "type": "plaintext",
        "value": "my secret content"
      },
      "category": "text"
    }
  }
}

{
  "data": {
    "id": "183b11e3-6413-4451-9b99-4632204d5c48",
    "type": "secret",
    "attributes": {
      "category": "text",
      "createdAt": "2025-03-25T21:30:29.423697+00:00",
      "createdBy": "1cc381f7-9c52-419f-ac7b-ae3cd6d148d4",
      "eventName": "create",
      "expiresAt": null,
      "requiresIdentityChallenge": false,
      "status": "active",
      "title": "Test public secret created",
      "updatedAt": "2025-03-25T21:30:29.423684+00:00",
      "updatedBy": "1cc381f7-9c52-419f-ac7b-ae3cd6d148d4",
      "version": 0,
      "versionId": "a94f260e-8f2e-40b8-b512-2f2c991309d4",
      "workspaceId": "5aab889c-db7d-4164-87b0-e07e57c36007",
      "workspaceName": "cerby"
    }
  }
}

Retrieve secret by ID

get

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

Important: The API scope required to use this endpoint is: Read secrets.

Path parameters

idstring · uuidRequired

The unique identifier of the secret.

Responses

200

OK - The JSON array with the secret objects requested on the specified page.

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

get

/secrets/{id}

HTTPcURLJavaScriptPython

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

{
  "data": {
    "attributes": {
      "body": {
        "type": "plaintext",
        "value": "These are the license keys for the software.\n\nSoftware1: 1234-56789-2\nSoftware 2: 20884HG-"
      },
      "category": "text",
      "createdAt": "2023-09-11T06:45:19.136000+00:00",
      "createdBy": "a4393f7e-1144-42e0-1234-fca77099f0a6",
      "eventName": "create",
      "expiresAt": null,
      "requiresIdentityChallenge": false,
      "status": "active",
      "title": "License keys",
      "updatedAt": "2023-09-11T06:53:21.302000+00:00",
      "updatedBy": "a4393f7e-1144-2345-b23b-fca77099f0a6",
      "version": 1,
      "versionId": "5199654b-cfc8-4624-1234-4f8a946fae60",
      "workspaceId": "5aab889c-db7d-1234-1234-e07e57c36007",
      "workspaceName": "cerby"
    },
    "id": "b968a1a-228e-1234-8556-1eea60687cba",
    "type": "secret"
  }
}

Retrieve the teams or users of a secret

get

With a GET request to the /secrets/{id}/members/{memberType} endpoint, you can retrieve the list of users or teams with shared access to a secret by providing their member type.

Important: The API scope required to use this endpoint is Read secrets.

Path parameters

idstringRequired

The unique identifier of the secret.

memberTypestring · enumRequired

The member type you want to list. The possible values are users or teams.

Possible values:

Query parameters

page[number]integer · min: 1Optional

The page number to retrieve in a paginated list.

Default: 1

page[size]integer · max: 100Optional

The number of items to display per page.

Default: 25

Responses

200

OK - The JSON array with the secret objects requested on the specified page.

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

get

/secrets/{id}/members/{memberType}

HTTPcURLJavaScriptPython

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

{
  "data": [
    {
      "id": "6d23c85b-d3f9-46c7-bb34-7c88680087c5",
      "type": "user",
      "attributes": {
        "role": "secret_owner"
      }
    },
    {
      "id": "faefda21-c3d2-48da-879f-a5ee112fa848",
      "type": "user",
      "attributes": {
        "role": "secret_collaborator"
      }
    },
    {
      "id": "a4393f7e-1144-42e0-b23b-fca77099f0a6",
      "type": "user",
      "attributes": {
        "role": "secret_owner"
      }
    }
  ],
  "links": {
    "next": null,
    "previous": null,
    "self": "/api/v1/secrets/a8b02608-6714-43a6-97c4-0a2277a7490f/members/users?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "page": {
      "maxSize": 100,
      "total": 10
    }
  }
}

Share a secret with a user or team

post

With a POST request to the /secrets/{id}/members/{memberType} endpoint, you can share a secret with a user or team by providing their member type.

Important: The API scope required is Write secrets.

Path parameters

idstringRequired

The unique identifier of the secret.

memberTypestring · enumRequired

The member type to which you want to share the secret. The possible values are users or teams.

Possible values:

Body

application/json

Responses

201

Created - The secret JSON object.

application/json

400

Bad request - The server could not interpret the request due to invalid syntax or missing parameters. Review your request and correct it.

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

post

/secrets/{id}/members/{memberType}

HTTPcURLJavaScriptPython

POST /api/v1/secrets/{id}/members/{memberType} HTTP/1.1
Host: my-workspace.cerby.com
Content-Type: application/json
Accept: */*
Content-Length: 142

{
  "data": {
    "id": "fd69061-efc4-4de7-ab52-2ecdd3cc0af6",
    "type": "users",
    "attributes": {
      "role": "secret_collaborator",
      "message": "Welcome to Cerby!"
    }
  }
}

{
  "data": {
    "id": "5fd69061-1234-4de7-ab52-2ecdd3cc0af6",
    "type": "user",
    "attributes": {
      "role": "secret_collaborator"
    }
  }
}