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

> Connect SailPoint IdentityIQ to Serval with a service account so workflows and the AI agent can read and manage identities and accounts, query entitlements and policy violations, and launch IdentityIQ workflows on demand.

## 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](/sections/integrations/sailpoint-identitysc) - or start from the [SailPoint overview](/sections/integrations/sailpoint) 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

| Capability                        | Description                                                                                                                                                                                                                                                                                                                  |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Full SCIM API access              | Workflows and the AI agent make typed requests across the IdentityIQ SCIM API surface: users, accounts, entitlements, roles, applications, alerts, policy violations, policy violation checks, launched workflows, workflows, task results, object configs, resource types, schemas, and the service provider configuration. |
| Identity and account management   | Query users, accounts, and entitlements with SCIM filters and pagination, and create, update, or delete users and accounts - the basis for access reviews and governance automations.                                                                                                                                        |
| Workflow launch and task tracking | Launch IdentityIQ workflows and inspect launched workflows and task results for provisioning and governance operations.                                                                                                                                                                                                      |
| Policy violation visibility       | Read policy violations and run policy violation checks for compliance-driven automations.                                                                                                                                                                                                                                    |
| Connection health checks          | Three built-in checks (Test Connection, List Users, List Accounts) verify authentication and read permissions from the app page.                                                                                                                                                                                             |

Anything defined in the [SailPoint IdentityIQ SCIM API](https://developer.sailpoint.com/docs/api/iiq/) 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](https://developer.sailpoint.com/).

<Steps>
  <Step title="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](https://identityiq.company.com/identityiq/scim/v2), with your own hostname in place of the example - if that address answers, Serval can reach it.
  </Step>

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

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

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

## Connect in Serval

<Steps>
  <Step title="Open the IdentityIQ connect form">
    In Serval, go to **Apps**, find **SailPoint IdentityIQ**, and click **Connect**. (The [SailPoint overview](/sections/integrations/sailpoint) explains the difference between the two SailPoint products.)
  </Step>

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

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

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

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

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

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

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

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

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Instance URL must be a bare hostname">
    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."
  </Accordion>

  <Accordion title="The SCIM API must be enabled and network-reachable">
    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.
  </Accordion>

  <Accordion title="Password rotation breaks the connection until updated">
    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.
  </Accordion>

  <Accordion title="Updating credentials from the app page">
    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.
  </Accordion>

  <Accordion title="Connected the wrong SailPoint product">
    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](/sections/integrations/sailpoint-identitysc), or use the [SailPoint overview](/sections/integrations/sailpoint) to confirm which one you have before connecting.
  </Accordion>
</AccordionGroup>

***

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