Skip to main content

​
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 instead, or start from the SailPoint overview. 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). An optional, feature-flagged per-user OAuth path lets certain actions run as the acting end user. 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

Anything defined in the SailPoint V2025 API 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 for full details, and SailPoint’s API authentication guide for how the client credentials grant works behind the scenes.
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.
1

Log into your ISC tenant

Sign in as the user whose permissions the integration should use.
2

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

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

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

Copy both values

Copy the Client ID and the Secret (this is the Client Secret). You will paste both into Serval.
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.
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.

​
Per-user (user-auth) OAuth

By default every workflow call runs as the service account (the PAT above). Optionally, workflows can call the ISC API as the individual user who triggered them - under that user’s own governance rights, with that user as the audit identity. Users connect their own SailPoint account to Serval once, then actions marked “as user” use their credential. Personal Access Tokens only support the client-credentials grant, so per-user auth needs a dedicated OAuth client in your tenant:
1

Create an OAuth client

In ISC, go to Admin > Global > Security Settings > API Management and create a new API client with the Authorization Code and Refresh Token grant types (you can also create it through the oauth-clients API).
2

Register Serval's redirect URL

Add the following as a redirect URL on the client:
If your Serval tenant is on the EU shard, use https://api.eu1.serval.com/v1/svflow-authconfig/sailpoint-identitysc/user/oauth/callback instead (ask support@serval.com if you’re unsure which region you’re on).
3

Add the client to your Serval connection

Edit the SailPoint ISC connection in Serval and paste the client’s ID and Secret into User-Auth OAuth Client ID and User-Auth OAuth Client Secret.
4

Choose the requested scopes

In User-Auth OAuth Scopes, click Choose scopes. Serval uses the connection’s Personal Access Token to read the configured OAuth client’s allowed scopes. Search the list and select the scopes your workflows need, then click Done and save the connection. Remove selected scopes using their chips.If SailPoint denies the lookup or the client can’t be reached, choose Browse documented scopes to search a catalog from SailPoint’s published API specifications. These suggestions aren’t verified for your client: confirm that your OAuth client allows them. Enter scopes manually is available for scopes missing from the catalog.New connections start with sp:scopes:all selected. Existing connections keep their saved scopes. To restrict the request, remove sp:scopes:all and select the approved scopes your workflows need. At least one scope is required: Update stays disabled while the selection is empty.These fields appear when per-user authentication is enabled for your organization. They don’t change the service account’s PAT scopes.
After changing scopes, have users reconnect their SailPoint accounts. Saving the connection doesn’t revoke or change existing tokens. Each user connects their SailPoint account the first time a workflow needs it - Serval fails the run with a personal connect link if they haven’t. Tokens are scoped by ISC to the connecting user’s own access level.

​
Connect in Serval

1

Open the SailPoint Identity Security Cloud integration

In Serval, go to your team’s integrations, find SailPoint Identity Security Cloud, and click Connect.
2

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”.
3

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”.
4

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

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).
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).
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. Credentials you leave untouched, or clear to blank, keep their stored values - so you can rotate just the secret without re-entering the Tenant Name or Client ID.

​
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.”
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.

​
Gotchas and troubleshooting

Check User-Auth OAuth Scopes against the scopes allowed by your SailPoint OAuth client. Use Choose scopes to replace sp:scopes:all with the approved scopes your workflows need, save the connection, and retry sign-in. The requested scopes must be allowed by SailPoint; changing this field doesn’t grant additional permissions to the client or user.
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.
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.
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.
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.
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 credentials you clear to blank also keep their stored values, so a secret rotation never requires re-entering the rest of the form.
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.
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.
Need help? Contact support@serval.com for assistance with your SailPoint Identity Security Cloud integration.