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

# CyberArk Privilege Cloud

> Connect Serval to your CyberArk Privilege Cloud (ISPSS) tenant via the Privilege Cloud REST API for privileged-access management workflows - safes, safe membership, credential rotation, and access-request approvals.

## About CyberArk Privilege Cloud

The CyberArk Privilege Cloud integration connects Serval to your CyberArk Privilege Cloud tenant - the SaaS PAM on CyberArk's Identity Security Platform Shared Services (ISPSS) - through the Privilege Cloud REST API. It powers privileged-access management workflows: listing safes and accounts, granting and revoking safe membership for just-in-time (JIT) access, triggering CPM credential rotation, and approving or rejecting dual-control access requests.

**Serval never retrieves or stores vaulted secret values.** The curated API surface excludes all credential-retrieval endpoints - workflows can manage who has access to safes and when credentials rotate, but there is no path through Serval to read a vaulted password.

**Authentication:** Username and password for a dedicated CyberArk Identity service user configured as an OAuth confidential client. Serval exchanges the credentials for a short-lived bearer token (`POST /oauth2/platformtoken`) and attaches it to every proxied request - workflow code never sees the password or the token.

**ISPSS tenants only.** Your tenant's API host must be on `*.privilegecloud.cyberark.cloud`. Legacy "Privilege Cloud Standard" tenants on `*.privilegecloud.cyberark.com` authenticate through the vault Logon API instead and are not supported by this integration.

**Data sync:** On demand only. There is no background sync of safes or accounts - Serval calls your tenant only when a workflow or health check runs.

## What the Privilege Cloud integration enables

| Capability                  | Description                                                                                                                  |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Safe and account visibility | List safes, safe members, and the accounts stored in safes your service user can see - metadata only, never secret values.   |
| JIT safe access             | Grant and revoke safe membership so privileged access can be provisioned just-in-time and cleaned up automatically.          |
| Credential rotation         | Trigger CPM-managed password change operations on accounts (CyberArk's CPM performs the rotation; Serval only initiates it). |
| Dual-control approvals      | List pending access requests and approve or reject them, so request/approve flows can run through Serval.                    |

<Note>
  **User and group management is out of scope (v1).** On ISPSS tenants, users, groups, and roles are managed in CyberArk Identity, not through the Privilege Cloud vault API - so user-lifecycle workflows (disable/offboard) are not part of this integration. Manage identities in CyberArk Identity directly or via an Identity-focused integration.
</Note>

## Prerequisites

Before connecting, make sure your tenant meets these requirements:

<Steps>
  <Step title="An ISPSS Privilege Cloud tenant">
    Your tenant must live on `*.privilegecloud.cyberark.cloud` (Shared Services). Legacy Privilege Cloud Standard tenants on `*.cyberark.com` are not supported.
  </Step>

  <Step title="Find your Identity tenant host">
    In the CyberArk Identity Administration portal, note your Identity tenant's host - it looks like `abc1234.id.cyberark.cloud`. This is the `id.cyberark.cloud` host, **not** the portal subdomain you type into a browser.
  </Step>

  <Step title="Create a dedicated service user in CyberArk Identity">
    Create a new Identity user for Serval (for example `svc-serval@acme.cyberark.cloud`) and, in its settings, enable **"Is OAuth confidential client"**. That flag blocks interactive login and exempts the account from MFA so the OAuth client-credentials exchange works. The username becomes the OAuth `client_id` and the password the `client_secret`.
  </Step>

  <Step title="Grant the service user a Privilege Cloud role">
    Add the service user to a role that grants access to Privilege Cloud (for example, a role with the Privilege Cloud Users right), then give it safe-level permissions for exactly the workflows you plan to install.
  </Step>
</Steps>

### Least-privilege guidance for the service user

Grant the service user only what the workflows you install actually need:

* **Membership on the safes Serval will manage**, with `manageSafeMembers` (for grant/revoke workflows), `listAccounts` (for account listing), and `initiateCPMAccountManagementOperations` (for rotation workflows).
* **Authorizer permissions (`requestsAuthorizationLevel1`)** on safes where Serval should approve or reject dual-control access requests.
* **No "Retrieve accounts" permission anywhere.** Serval's API surface has no credential-retrieval endpoints, but the account should not hold that permission regardless - defense in depth.

## Connect in Serval

<Steps>
  <Step title="Select CyberArk Privilege Cloud">
    In Serval, open your team's integrations page and select **CyberArk Privilege Cloud**.
  </Step>

  <Step title="Enter the API Host (required)">
    Enter your tenant's API host, for example `acme.privilegecloud.cyberark.cloud`. You do not need to include `https://` - Serval normalizes the value and always connects over HTTPS. The host must end with `.cyberark.cloud`.
  </Step>

  <Step title="Enter the Identity Tenant Host (required)">
    Enter your CyberArk Identity tenant host, for example `abc1234.id.cyberark.cloud` (from Identity Administration). This is where Serval sends the OAuth token request.
  </Step>

  <Step title="Enter the Service User and Password (required)">
    Enter the dedicated service user's username and password. Serval stores the password encrypted and uses it only inside the proxy as the OAuth client credentials.
  </Step>

  <Step title="Save and verify">
    Submit the form. Serval authenticates and runs the health checks (below).
  </Step>
</Steps>

<Note>
  **Token behavior:** Serval exchanges the credentials at `POST https://{identityHost}/oauth2/platformtoken` and caches the resulting bearer token for the lifetime the response reports (typically 15 minutes), refreshing shortly before expiry. No refresh token is involved - Serval simply repeats the exchange when needed.
</Note>

## Verifying the connection

Four health checks run after you connect:

1. **Test Connection** - authenticates against CyberArk Identity and lists safes. Failure usually means the Identity tenant host is wrong, the service user is missing **"Is OAuth confidential client"**, or the username/password is incorrect.
2. **List Safes** - confirms the service user can enumerate safes. Failure with a working Test Connection means the account has no safe memberships or lacks list rights.
3. **List Accounts** - confirms the account can list accounts in its safes. Failure typically means the account is missing `listAccounts` on the managed safes.
4. **List Platforms** - confirms the account can read target platforms (needed to discover valid platform IDs for account workflows).

<Tip>
  If Test Connection fails outright, fix the Identity tenant host and service-user setup first. If it passes but a later check fails, the service user authenticates fine and is just missing a CyberArk permission - adjust its role or safe memberships.
</Tip>

## Installable workflows

The integration ships with installable workflows (names indicative):

| Workflow                     | Type  |
| ---------------------------- | ----- |
| List Safes                   | Read  |
| List Safe Members            | Read  |
| List Accounts                | Read  |
| Grant Safe Access            | Write |
| Revoke Safe Access           | Write |
| Rotate Account Credentials   | Write |
| List Pending Access Requests | Read  |
| Approve Access Request       | Write |
| Reject Access Request        | Write |

<Note>
  Write workflows default to **installer approval**: when a help-desk conversation or automation reaches a write step, the workflow pauses for sign-off from the installing team before the change is made in CyberArk.
</Note>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Serval cannot read vaulted secrets - by design">
    The curated API surface excludes every credential-retrieval endpoint, so no workflow (prebuilt or custom) can fetch a vaulted password through Serval. If a workflow needs to hand a credential to a person, do that inside CyberArk (for example via a dual-control access request that Serval approves), not through Serval.
  </Accordion>

  <Accordion title="Legacy Privilege Cloud Standard tenants are not supported">
    Tenants on `*.privilegecloud.cyberark.com` use the vault Logon API rather than Identity OAuth. Serval validates that both configured hosts end with `.cyberark.cloud` and rejects legacy hosts at install time. If you are on a Standard tenant, this integration will not connect.
  </Accordion>

  <Accordion title="The service user must be an OAuth confidential client">
    Without **"Is OAuth confidential client"** enabled in CyberArk Identity, the `platformtoken` exchange fails - the account is subject to interactive login policies and MFA that an API client cannot satisfy. Enable the flag on the dedicated service user, not on a human account.
  </Accordion>

  <Accordion title="Use the Identity tenant host, not the portal subdomain">
    The token request goes to your Identity tenant host (`abc1234.id.cyberark.cloud`, shown in Identity Administration). Entering the Privilege Cloud portal hostname or your company's vanity login URL there will make authentication fail even with correct credentials.
  </Accordion>

  <Accordion title="Service-user permissions drive every workflow">
    CyberArk enforces authorization on the service user you configure. A grant/revoke workflow fails if the account lacks `manageSafeMembers` on the target safe; rotation fails without `initiateCPMAccountManagementOperations`. Grant per-safe permissions for exactly the workflows you install.
  </Accordion>

  <Accordion title="Rotation is asynchronous">
    Rotate Account Credentials marks the account for a CPM-managed change; the CPM performs the rotation on its own schedule. A successful workflow run means the operation was queued, not that the password has already changed.
  </Accordion>

  <Accordion title="Vault user management lives in CyberArk Identity">
    Unlike the self-hosted product, ISPSS tenants manage users, groups, and roles in CyberArk Identity - the vault user endpoints are not part of this integration's API surface, and there is no disable-user workflow in v1.
  </Accordion>
</AccordionGroup>

***

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