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

# SailPoint Identity Security Cloud

> Connect Serval to SailPoint Identity Security Cloud (ISC) so workflows can read identities and accounts, govern access, and automate access requests and certifications through the ISC V2025 API.

## About SailPoint Identity Security Cloud

SailPoint Identity Security Cloud (ISC), formerly IdentityNow, is SailPoint's SaaS identity governance platform. Serval connects to a single ISC tenant using the Client ID and Client Secret from a SailPoint Personal Access Token, and gives your workflows access to the full ISC V2025 REST API - 537 endpoints covering identities, accounts, access profiles, certifications, sources, and more. Serval only ever sends these credentials to your tenant's API host under api.identitynow\.com. ISC is one of two SailPoint products Serval supports: if you run the on-premises product, see [SailPoint IdentityIQ](/sections/integrations/sailpoint-identityiq) instead, or start from the [SailPoint overview](/sections/integrations/sailpoint).

**Authentication:** OAuth 2.0 client credentials, using a SailPoint Personal Access Token (Client ID + Client Secret). Serval exchanges these for short-lived access tokens automatically - the only credential to manage over time is the token itself, which carries an expiration date you set in SailPoint (6 months by default).

**Data sync:** On-demand only. There is no scheduled background sync, no entity ingestion, and no prebuilt install workflows - your workflows call the ISC API at run time.

## What the SailPoint Identity Security Cloud integration enables

| Capability                                  | Description                                                                                                                                 |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Read identities                             | List and read identities, public identities, identity profiles, and historical identities.                                                  |
| Read accounts                               | List and read accounts and their entitlements, including account lifecycle operations.                                                      |
| Govern access profiles and entitlements     | Query and manage the access profiles and entitlements that back access requests, certifications, and provisioning.                          |
| Automate access requests and certifications | Submit and track access requests, access-request approvals, certifications, and certification campaigns.                                    |
| Manage sources, roles, and workgroups       | The API's largest families - sources, roles, role mining, certifications, work items, identities, and accounts - are all reachable.         |
| Call any V2025 API endpoint                 | A generic API request action reaches any of the 537 endpoints (781 operations) in the bundled V2025 spec that your token is authorized for. |

Anything defined in the [SailPoint V2025 API](https://developer.sailpoint.com/docs/api/v2025/) can be accessed through Serval.

## Get your credentials

Serval authenticates with a SailPoint **Personal Access Token (PAT)**. Creating one gives you the Client ID and Client Secret that Serval needs. See [SailPoint's Personal Access Tokens documentation](https://documentation.sailpoint.com/saas/help/common/api_keys.html) for full details, and [SailPoint's API authentication guide](https://developer.sailpoint.com/docs/api/authentication) for how the client credentials grant works behind the scenes.

<Note>
  A PAT can never do more than the user who creates it, and it is further limited by the scopes you select when you create it - Serval requests no additional scopes of its own. Generate the token from a user whose governance rights cover everything you want Serval to do, and select **sp:scopes:all** unless you deliberately want to restrict it.
</Note>

<Steps>
  <Step title="Log into your ISC tenant">
    Sign in as the user whose permissions the integration should use.
  </Step>

  <Step title="Open Personal Access Tokens">
    Select the user icon in the upper-right corner, choose **Preferences**, then select **Personal Access Tokens** from the left menu - or navigate directly to `https://[tenant].identitynow.com/ui/d/user-preferences/personal-access-tokens`.
  </Step>

  <Step title="Create the token">
    Click **New Token** and describe the token's purpose in the **What is this token for?** field (for example "Serval Integration"). Set the expiration date deliberately: it defaults to 6 months out, and leaving it blank creates a token that never expires.
  </Step>

  <Step title="Select scopes">
    Use the scope toggles to select **sp:scopes:all**, which authorizes the token for everything its creator's access level allows. If you select no scopes at all, SailPoint assigns a default scope that only reaches endpoints requiring no authorization - Serval's health checks will fail with a token like that. Then click **Create Token**.
  </Step>

  <Step title="Copy both values">
    Copy the **Client ID** and the **Secret** (this is the Client Secret). You will paste both into Serval.
  </Step>
</Steps>

<Warning>
  The Secret is shown only once, at creation. If you close the dialog without saving it, you must create a new token. SailPoint also limits each user to 10 Personal Access Tokens - the **New Token** button is disabled once you hit the cap - so delete unused tokens before creating new ones.
</Warning>

<Tip>
  Your tenant name is the subdomain of your ISC URL - `acme-corp` from `acme-corp.identitynow.com`. Admins can confirm it by opening the **Dashboard** dropdown, selecting **Overview**, and finding the Org Name in the Org Details section. If your org signs in through a vanity URL, the subdomain is not your tenant name - use the Org Name from the dashboard, or open `https://[tenant].api.identitynow.com/oauth/info` in a browser and use the `tenantName` value it returns.
</Tip>

## Connect in Serval

<Steps>
  <Step title="Open the SailPoint Identity Security Cloud integration">
    In Serval, go to your team's integrations, find **SailPoint Identity Security Cloud**, and click **Connect**.
  </Step>

  <Step title="Enter your Tenant Name (required)">
    Enter just the tenant identifier - helper text reads "Your ISC tenant name (e.g. acme-corp from acme-corp.api.identitynow\.com)". Do not paste a full URL: there is no format check, and Serval uses the value verbatim to build the API address, so a URL here breaks the connection. Leaving it blank shows "This field is required".
  </Step>

  <Step title="Enter your Client ID (required)">
    Paste the Client ID from your Personal Access Token - helper text reads "Client ID from your Personal Access Token". Leaving it blank shows "This field is required".
  </Step>

  <Step title="Enter your Client Secret (required)">
    Paste the Client Secret from the same token into this password field - helper text reads "Client secret from your Personal Access Token". Unlike the other two fields, the form will not stop you from submitting with this one empty - the mistake only surfaces when the health checks run, so double-check the secret made it in.
  </Step>

  <Step title="Submit the form">
    Click **Submit**. Serval stores the credentials and names the connection after your tenant. If installation fails, the form shows "Failed to install integration" (with details appended when available).
  </Step>
</Steps>

<Note>
  Serval does not test the credentials when you save - a mistyped tenant name or secret is accepted at save time and only surfaces when the health checks run. Run them right after connecting (see below).
</Note>

<Tip>
  When you edit an existing connection, the form opens pre-filled with your saved values: Tenant Name and Client ID appear as entered, and the Client Secret appears masked (bullet characters plus its last 4 characters) next to a **Replace** button. To rotate the secret, click **Replace** and paste the complete new secret into the "Enter new value" box. Anything you leave untouched, or clear to blank, keeps its stored value - so you can rotate just the secret without re-entering the Tenant Name or Client ID.
</Tip>

## Verifying the connection

The integration runs three health checks:

* **Test Connection** - makes a minimal read of public identity data to confirm Serval can authenticate and reach your tenant's API. On success: "Successfully connected to SailPoint Identity Security Cloud API." If your credentials are rejected: "Authentication failed. Please verify your Client ID and Client Secret are correct." For any other failure (for example a mistyped tenant name): "Unable to connect to SailPoint Identity Security Cloud. Please verify your tenant name and credentials."
* **List Identities** - makes a minimal identity read to confirm the credentials can see identity data. On success: "Successfully listed identities." On failure: "Unable to list identities. Please verify the configured credentials have permission to read identity data."
* **List Accounts** - makes a minimal account read to confirm the credentials can see account data. On success: "Successfully listed accounts." On failure: "Unable to list accounts. Please verify the configured credentials have permission to read account data."

<Tip>
  If Test Connection is green but a workflow step fails with a permission (403) error, your credentials are valid but the token lacks rights for that specific operation. Recreate the token from a user with the needed governance authority - with **sp:scopes:all** selected - and update the connection. The List Identities and List Accounts checks surface the most common read-permission gaps directly.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Enter the tenant name only, never a full URL">
    Serval builds the API address directly from the Tenant Name field with no format validation. Enter just the identifier (`acme-corp`), not `https://acme-corp.identitynow.com`. If your org uses a vanity URL, recover the real tenant name from the Org Name on your dashboard's Overview page, or from the `tenantName` value at `https://[tenant].api.identitynow.com/oauth/info`.
  </Accordion>

  <Accordion title="403 errors: the token can only do what its creator and scopes allow">
    A Personal Access Token never exceeds the governance authority of the ISC user who created it, and it is further narrowed by the scopes selected at creation - Serval requests no additional scopes. 403 Forbidden responses mean the token lacks rights for that operation: recreate it from a user with the needed authority, select **sp:scopes:all**, and update the connection. The List Identities and List Accounts health checks surface this directly.
  </Accordion>

  <Accordion title="Client Secret is shown once; users are capped at 10 PATs">
    SailPoint displays the Secret only at token creation, and each user can hold at most 10 Personal Access Tokens - the **New Token** button is disabled at the cap. Store the secret before closing the dialog; if it is lost, create a new token and update the connection.
  </Accordion>

  <Accordion title="Personal Access Tokens expire after 6 months by default">
    When you create a PAT, SailPoint sets its expiration 6 months out unless you change it (a blank expiration date means the token never expires). When the token lapses, the connection's health checks start failing with authentication errors even though nothing changed in Serval. You can extend the expiration date in SailPoint before it lapses - SailPoint even lets you restore an expired token by updating its date for up to 3 months afterward - or create a new token and update the connection's Client ID and Client Secret.
  </Accordion>

  <Accordion title="Editing the connection: untouched fields keep their saved values">
    The edit form opens pre-filled. The Client Secret shows as a masked, read-only value with a **Replace** button - click **Replace** and paste the full new secret to rotate it. Tenant Name and Client ID stay as saved unless you type over them, and a field you clear to blank also keeps its stored value, so a secret rotation never requires re-entering the rest of the form.
  </Accordion>

  <Accordion title="Changing the Tenant Name re-points the whole connection">
    A new Tenant Name re-derives the API address and renames the connection. The existing Client ID and Client Secret are kept unless you also replace them, so after a tenant change you almost always need to supply credentials from a PAT created in the new tenant too.
  </Accordion>

  <Accordion title="Workflow API calls: the version prefix is added for you">
    For builders: the generic API request action automatically adds the `v2025` version prefix to every path, so pass paths without it. Path parameters use curly-brace placeholders filled in through the action's path parameters, not colon-style. List endpoints paginate with `limit` and `offset`; requesting an exact total count is expensive on large tenants, so ask for it only when you need it.
  </Accordion>
</AccordionGroup>

***

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