> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cerby

> Connect Cerby to Serval with a workspace API token so workflows can read account inventory, retrieve passwords and TOTP codes, manage users, teams, collections, and secrets, and drive provisioning in Cerby's business hub integrations.

## About Cerby

[Cerby](https://cerby.com) 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

| Capability                               | Description                                                                                                                                                                                                                                                                                 |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Account inventory and secret reads       | List all accounts, retrieve an account by id, list the users on an account, read an account's password (only for accounts stored in an AWS KMS vault), and retrieve the account's current TOTP code.                                                                                        |
| Account and secret sharing               | Share accounts with users or teams; list, create, and retrieve secrets; list and share a secret's user and team members.                                                                                                                                                                    |
| Collection management                    | List collections, retrieve, update, or delete a collection, add resources to a collection, list subcollections, and list, add, or remove the accounts, secrets, users, and teams in a collection.                                                                                           |
| User management                          | List and create workspace users, retrieve and update a user, and list a user's accounts, secrets, collections, and teams.                                                                                                                                                                   |
| Team management                          | List and create teams, retrieve, update, or delete a team, list and add team members, and list a team's accounts, secrets, and collections.                                                                                                                                                 |
| Business hub integrations (provisioning) | List Cerby's connected business hub integrations, retrieve one by id, list, retrieve, invite, or remove integration users, list entitlements, update a user's entitlements (replace the set, or add and remove individual entitlements), list integration assets, and list unmatched users. |
| Job monitoring                           | Retrieve an asynchronous job by id to poll automated operations (such as inviting a user or updating an entitlement) until completion.                                                                                                                                                      |
| Vaults and raw API access                | List vaults, plus a flexible "Cerby API request" action that covers every endpoint in the Cerby v1 API.                                                                                                                                                                                     |

Anything defined in the [Cerby API](https://developer.cerby.com/) 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](https://developer.cerby.com/).

<Steps>
  <Step title="Open the API Keys page in Cerby">
    Sign in to Cerby and go to **Settings > Developer > API Keys**.
  </Step>

  <Step title="Create the key">
    Click **Create API Key** and give it a descriptive name (e.g. "Serval Integration").
  </Step>

  <Step title="Select scopes">
    Select the scopes your workflows need - at minimum **Read vaults**, **Read users**, **Read items**, and **Read integrations**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Note your workspace name">
    It's the subdomain of your Cerby URL: for [https://acme.cerby.com](https://acme.cerby.com) the workspace name is "acme".
  </Step>
</Steps>

<Warning>
  The API key is displayed a single time at creation. Store it securely - Cerby will not show it again.
</Warning>

<Note>
  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.
</Note>

## Connect in Serval

<Steps>
  <Step title="Open the Cerby connect form in Serval">
    Add a new Cerby connection from your Serval integrations page. The tile carries a Beta label.
  </Step>

  <Step title="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".
  </Step>

  <Step title="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".
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## 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."

<Tip>
  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.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="The workspace name is the bare slug, not a URL or domain">
    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.
  </Accordion>

  <Accordion title="Teams checks fail while user checks pass">
    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.
  </Accordion>

  <Accordion title="Password reads only work for accounts in an AWS KMS vault">
    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.
  </Accordion>

  <Accordion title="The API key is displayed only once">
    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).
  </Accordion>

  <Accordion title="The integration is marked Beta">
    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.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Cerby integration.