Skip to main content

​
About Cerby

Cerby is an identity, access, and password management platform for “disconnected” applications - apps without SSO or SCIM support, and seat-licensed social and marketing tools. Connecting Cerby to Serval lets workflows read your account inventory and MFA state, retrieve passwords and TOTP codes from Cerby-managed vaults, manage users, teams, collections, and secrets, and drive user provisioning and entitlement changes in Cerby’s connected business hub integrations. Serval talks only to your own workspace’s Cerby address (for example acme.cerby.com) and attaches your API token to every request. The integration is currently marked Beta, so the Cerby tile appears with a Beta label in the connect catalog. Authentication: API key (a Cerby workspace API token plus your workspace name) Data sync: On-demand only. There is no background sync, resource import, or scheduled polling - Serval calls Cerby only when a workflow runs, and verifies the connection with lightweight read-only health checks.

​
What the Cerby integration enables

Anything defined in the Cerby API can be accessed through Serval.

​
Get your credentials

Serval needs a Cerby workspace API key. Under Cerby’s role-based access control, the key can do exactly what its selected scopes and its creator’s workspace role allow. Grant at minimum the four read scopes the connection’s health checks exercise - Read vaults, Read users, Read items, and Read integrations. Add Read accounts if your workflows will read accounts, passwords, or TOTP codes, Read secrets for secret reads, and write scopes (for example Write accounts, Write collections, Write secrets, Write integrations) only if your workflows will make changes. Create the key as a user with at least an Admin workspace role (Admin, Super Admin, or Owner) - Cerby’s teams area requires it, so a key created by a lower-role user fails the teams health check. Cerby’s developer documentation is here: Cerby API documentation.
1

Open the API Keys page in Cerby

Sign in to Cerby and go to Settings > Developer > API Keys.
2

Create the key

Click Create API Key and give it a descriptive name (e.g. “Serval Integration”).
3

Select scopes

Select the scopes your workflows need - at minimum Read vaults, Read users, Read items, and Read integrations.
4

Copy the key immediately

Cerby shows the generated key only once. Copy it before closing the page - if it’s lost, you must create a new key.
5

Note your workspace name

It’s the subdomain of your Cerby URL: for https://acme.cerby.com the workspace name is “acme”.
The API key is displayed a single time at creation. Store it securely - Cerby will not show it again.
The connection can do exactly what the key’s scopes allow, no more. Some areas (like teams) also require the key’s owning user to hold an Admin-level workspace role - see the gotchas below.

​
Connect in Serval

1

Open the Cerby connect form in Serval

Add a new Cerby connection from your Serval integrations page. The tile carries a Beta label.
2

Enter the Workspace name

The Workspace name field is required and described as ‘The Cerby workspace slug from your URL (e.g. “acme” for acme.cerby.com).’ Enter only the bare slug - lowercase letters, numbers, and hyphens. If the value contains “.cerby.com”, a scheme like “https://”, uppercase letters, a leading hyphen, dots, or underscores, the form rejects it with: Lowercase letters, numbers, and hyphens only. Do not include “.cerby.com”. Leaving it blank shows “This field is required”.
3

Paste the API Token

The API Token field is required and described as “API key generated in the Cerby web app under Settings -> Developer -> API Keys.” Paste the full key you copied from Cerby. Leaving it blank shows “This field is required”.
4

Save the connection

Serval builds your workspace’s Cerby address from the slug. Use the health checks below to confirm Serval can reach the Cerby API with your token.
When you edit an existing connection, the workspace name is shown back as the plain slug and the stored token appears masked (bullets plus its last 4 characters) alongside a control to replace it. Leave the masked token as it is to keep your existing stored token; to rotate it, choose to replace it and paste the entire new key.

​
Verifying the connection

The Cerby connection ships with five health checks. Each one exercises a different permission, so a failure pinpoints exactly which scope (or role) the key is missing. The four list checks append your workspace total when Cerby returns one - for example “Successfully listed users from Cerby (workspace total: 42).” They also run again automatically whenever you save changes to the connection’s settings.
  • Validate Cerby API connection - confirms the token can reach the Cerby API by listing vaults (a lightweight read that exercises the Read vaults scope). On success: “Successfully connected to the Cerby API.” On failure: “Unable to connect to the Cerby API. Verify the workspace subdomain and that the API token has the Read vaults scope.”
  • List Cerby users - confirms the Read users scope by listing a single user. On success: “Successfully listed users from Cerby.” On failure: “Unable to list users from Cerby. Verify the API token has the Read users scope.”
  • List Cerby teams - confirms the token can read teams. On success: “Successfully listed teams from Cerby.” On failure: “Unable to list teams from Cerby. Verify the API token has the Read users scope and that the user has at least an Admin role.”
  • List Cerby integrations - confirms the Read integrations scope by listing one connected business hub integration. On success: “Successfully listed integrations from Cerby.” On failure: “Unable to list integrations from Cerby. Verify the API token has the Read integrations scope.”
  • List Cerby collections - confirms the Read items scope by listing one collection. On success: “Successfully listed collections from Cerby.” On failure: “Unable to list collections from Cerby. Verify the API token has the Read items scope.”
If “List Cerby users” passes but “List Cerby teams” fails, the problem is usually not a scope: Cerby’s teams area requires the key’s owning user to hold at least an Admin workspace role (Admin, Super Admin, or Owner). Recreate the key as a user with that role.

​
Gotchas and troubleshooting

Enter only the subdomain - “acme” for acme.cerby.com. Values containing “.cerby.com”, a scheme like “https://”, uppercase letters, leading hyphens, dots, or underscores are rejected with: Lowercase letters, numbers, and hyphens only. Do not include “.cerby.com”. Serval builds the full workspace address from the slug for you, and only ever sends your token to your workspace’s own cerby.com subdomain.
Cerby’s teams area requires the Read users scope plus at least an Admin workspace role (Admin, Super Admin, or Owner). If the “List Cerby teams” health check fails while “List Cerby users” passes, the API key’s owning user likely lacks the required workspace role rather than a scope - create the key as an Admin-level user.
Retrieving an account’s password is only available for accounts stored in an AWS KMS vault - reads against accounts in other vault types fail by design on Cerby’s side. Retrieving an account’s TOTP code requires the Read accounts scope.
Cerby shows the generated key a single time at creation. Copy it immediately and store it securely. If it’s lost, create a new key in Cerby, then edit the Serval connection, replace the masked API Token value, and paste the new key (leaving the masked value as it is keeps the old, now-dead key stored).
Cerby appears with a Beta label in the Serval connect catalog. Functionality described on this page is available today, but the integration’s surface may still evolve.
Need help? Contact support@serval.com for assistance with your Cerby integration.