Skip to main content

​
About SailPoint IdentityIQ

SailPoint IdentityIQ is SailPoint’s on-premises identity governance platform. Serval connects to your IdentityIQ server through its SCIM API using a username and password for a service account on your instance - there is no OAuth flow or sign-in redirect. Serval stores the credentials securely and sends them, as basic authentication, only with requests to the IdentityIQ server you configure. The integration is request-driven: Serval workflows and the AI agent read users, accounts, entitlements, roles, and policy violations, manage users and accounts, and launch IdentityIQ workflows, all on demand. If you use SailPoint’s cloud product instead, see the SailPoint Identity Security Cloud setup guide - or start from the SailPoint overview if you are not sure which one you have. Authentication: Basic authentication - a dedicated IdentityIQ service account username and password, stored securely by Serval. Data sync: No background or scheduled sync. All data access happens on demand when a workflow or the AI agent makes a request.

​
What the SailPoint IdentityIQ integration enables

Anything defined in the SailPoint IdentityIQ SCIM API can be accessed through Serval.

​
Get your credentials

Serval needs three things: your IdentityIQ server hostname, and the username and password of a service account that can use the SCIM API. There is no OAuth app, API token, or client credentials to create. SailPoint’s API documentation lives on the SailPoint Developer Community.
1

Confirm the SCIM API is enabled and reachable

Ask your IdentityIQ administrator to confirm the SCIM API is enabled on your instance and reachable from outside your network (or via your allowed network path). The SCIM address is https://identityiq.company.com/identityiq/scim/v2, with your own hostname in place of the example - if that address answers, Serval can reach it.
2

Create or choose a dedicated service account

Create (or pick) a service account in IdentityIQ with permission to use the SCIM API and read the resources you plan to automate against - users, accounts, entitlements, and so on.
3

Note the server hostname exactly

Record the hostname exactly as Serval should call it - for example identityiq.company.com. Hostname only: no https:// prefix and no trailing path.
Use a dedicated service account, not a personal admin account. Serval replays the stored username and password on every request, so if the account’s password changes in IdentityIQ - for example when an employee rotates their own credentials - the connection breaks until the password is updated in Serval.

​
Connect in Serval

1

Open the IdentityIQ connect form

In Serval, go to Apps, find SailPoint IdentityIQ, and click Connect. (The SailPoint overview explains the difference between the two SailPoint products.)
2

Enter the Instance URL

Instance URL is required (marked with an asterisk) and described as “Your IdentityIQ server hostname (e.g. identityiq.company.com)”. Enter the hostname only - no https:// prefix and no path. Leaving it empty shows “This field is required”.
3

Enter the Username

Username is required and described as “IdentityIQ admin username”. Use your dedicated service account. Leaving it empty shows “This field is required”.
4

Enter the Password

Password is required and described as “IdentityIQ admin password”. It is entered as a hidden password field. The form does not flag a missing password before submitting, so double-check it is filled in - an empty password is only caught later, when the health checks fail.
5

Submit the form

Click Submit (the button reads “Submitting…” while saving). If installation fails, an error appears starting with “Failed to install integration”, with details appended when available.
Serval does not validate the hostname format or test the credentials at save time - typos only surface when the health checks run. Run them right after connecting (see below).
To edit the connection later, open the API Integration tab on the SailPoint IdentityIQ app page. The form comes pre-filled: Instance URL and Username show their saved values, and the saved password appears masked - bullet characters plus its last 4 characters - next to a Replace button. To rotate the password, click Replace and type the complete new password; leaving it untouched (or blank) keeps the saved password. The Update button stays disabled until you change something. A successful save shows “Configuration updated successfully”; failures show “Failed to update configuration”.

​
Verifying the connection

Run the health checks from the API Integration tab on the SailPoint IdentityIQ app page. Re-run them whenever you update the connection’s credentials.
  • Test Connection - reads the SCIM service configuration to verify Serval can reach your instance and sign in. Success: “Successfully connected to SailPoint IdentityIQ SCIM API.” Failure: “Unable to connect to SailPoint IdentityIQ. Please verify your instance URL and credentials.” If the server rejects the credentials specifically (a 401 Unauthorized response), the failure reads “Authentication failed. Please verify your IdentityIQ username and password are correct.”
  • List Users - asks the SCIM API for a single user to verify the credentials can read user data. Success: “Successfully listed users. Total users found: [number].” (the count reads “unknown” if your server does not report a total). Failure: “Unable to list users. Please verify the configured credentials have permission to read user data.”
  • List Accounts - asks the SCIM API for a single account to verify the credentials can read account data. Success: “Successfully listed accounts. Total accounts found: [number].” (or “unknown”). Failure: “Unable to list accounts. Please verify the configured credentials have permission to read account data.”
A green Test Connection with a failing List Users or List Accounts means Serval can reach the server and sign in, but the service account lacks SCIM read permission on that resource. Fix the account’s permissions in IdentityIQ - the Instance URL and password are already correct.

​
Gotchas and troubleshooting

Enter only the server hostname (for example identityiq.company.com) - no https:// prefix and no path. Serval automatically adds the SCIM API path to every request, so including any path in the Instance URL produces malformed request addresses and the Test Connection check fails with “Unable to connect to SailPoint IdentityIQ. Please verify your instance URL and credentials.”
Because IdentityIQ is self-hosted, Serval can only connect if your server is reachable from Serval and the SCIM API is enabled on the instance. If either is not true, Test Connection fails with “Unable to connect to SailPoint IdentityIQ. Please verify your instance URL and credentials.” Ask your IdentityIQ administrator to confirm both, then re-run the check.
Serval sends the stored username and password on every request. If the service account’s password is rotated in IdentityIQ, requests start failing and Test Connection reports “Authentication failed. Please verify your IdentityIQ username and password are correct.” Update the password on the connection in Serval (click Replace next to the masked value on the API Integration tab) to restore it. Using a dedicated service account prevents an individual’s routine credential rotation from taking the integration down.
On the API Integration tab, Instance URL and Username come pre-filled with their saved values - edit them in place. Clearing either one blocks the save with “Instance URL is required” or “Username is required”. The saved password is shown masked with a Replace button: click it and type the complete new password to rotate it, or leave the password untouched (or blank) to keep the saved one. Saving does not re-test the credentials, so re-run the health checks from the same tab afterward to confirm the new values work.
This page covers the on-premises product, IdentityIQ. If your organization uses SailPoint’s cloud platform (Identity Security Cloud, formerly IdentityNow), the connection works differently - see the SailPoint Identity Security Cloud setup guide, or use the SailPoint overview to confirm which one you have before connecting.
Need help? Contact support@serval.com for assistance with your SailPoint IdentityIQ integration.