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

# PingID

> Connect Serval to PingOne so workflows can manage user MFA devices and call PingOne Management and MFA APIs.

## About PingID

PingID (PingOne) is Ping Identity's cloud identity platform. The Serval PingID integration connects to your PingOne environment using a **worker application** with OAuth 2.0 client credentials. Workflows can list and reset MFA devices, add SMS authenticators, and call PingOne Management and MFA APIs with typed request schemas. The integration is marked **Beta** in Serval's connect UI.

**Authentication:** OAuth 2.0 client credentials against your PingOne environment. Serval exchanges the Client ID and Client Secret for short-lived bearer tokens at `https://auth.{region}/{environmentId}/as/token` and attaches them to API requests at `https://api.{region}`.

**Data sync:** On demand only. There is no background user or group sync.

## What the PingID integration enables

| Capability            | Description                                                                                                                                                       |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MFA Management bundle | Prebuilt workflows: list a user's MFA devices, add an SMS device, activate a pending device with an OTP, unpair one device, and reset all MFA devices for a user. |
| PingID API request    | Typed MFA operations from the hand-authored PingOne MFA spec.                                                                                                     |
| PingOne API discovery | Full PingOne Management and MFA endpoint catalogs are indexed for workflow authoring, even when request bodies are untyped in the broader specs.                  |

Mutating MFA workflows ship with **installer approval** by default.

## Get your credentials

You need your PingOne **Environment ID**, a **worker application** Client ID and Client Secret, and the **region** that hosts your environment.

<Steps>
  <Step title="Open the PingOne admin console">
    Sign in to the PingOne admin console for your organization.
  </Step>

  <Step title="Copy the Environment ID">
    Go to **Settings → Environment Properties** and copy the Environment ID (a UUID).
  </Step>

  <Step title="Create or select a worker application">
    Under **Connections → Applications**, create a **Worker** application (or reuse an existing one). Assign roles that include **Identity Data Admin** and the MFA permissions your workflows need.
  </Step>

  <Step title="Copy the Client ID and Client Secret">
    From the worker application's **Overview** tab, copy the Client ID and Client Secret.
  </Step>

  <Step title="Note your region">
    Select the PingOne region that matches your environment: North America (`api.pingone.com`), Canada (`api.pingone.ca`), Europe (`api.pingone.eu`), Asia-Pacific (`api.pingone.asia`), or Australia (`api.pingone.com.au`).
  </Step>
</Steps>

<Warning>
  Worker applications are machine credentials with broad API access. Restrict the application's roles to the smallest set that covers your Serval workflows.
</Warning>

## Connect in Serval

<Steps>
  <Step title="Open the PingID connect form">
    In Serval, add the PingID integration. It is labeled **Beta**.
  </Step>

  <Step title="Region (required)">
    Select the PingOne API domain for your environment.
  </Step>

  <Step title="Environment ID (required)">
    Paste the UUID from Environment Properties.
  </Step>

  <Step title="Client ID (required)">
    Paste the worker application's Client ID.
  </Step>

  <Step title="Client Secret (required)">
    Paste the worker application's Client Secret in the password field.
  </Step>

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

<Note>
  When editing an existing connection, blank or obfuscated fields keep their stored values. Paste a new Client Secret to rotate credentials without re-entering the Environment ID.
</Note>

## Verifying the connection

Three health checks run after you connect:

1. **Test PingID Connection** — reads the environment record. Success: `Successfully authenticated with PingOne`. Failure includes region- or credential-specific guidance from the integration.
2. **List PingOne Users** — fetches one user from `/environments/{environmentID}/users`. Confirms Identity Data read access.
3. **List PingOne Populations** — reads populations in the environment. Confirms directory read access beyond authentication alone.

<Tip>
  If the connection test passes but user or population checks fail, the worker application authenticates but lacks Identity Data Admin (or equivalent) read permissions. Adjust the application's role assignment in PingOne.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Use a Worker application, not a native OIDC app">
    Serval uses the client-credentials grant. Browser-based or authorization-code applications will not exchange tokens the way this integration expects.
  </Accordion>

  <Accordion title="Region and Environment ID must match">
    A North America Client ID against an EU environment (or mismatched Environment ID) fails token exchange before any MFA workflow runs.
  </Accordion>

  <Accordion title="MFA reset workflows are destructive">
    **Reset All PingID MFA Devices** removes every enrolled factor for the target user. They must re-enroll on next sign-in. Keep installer approval enabled unless your team explicitly wants open access.
  </Accordion>

  <Accordion title="User targeting is by email">
    MFA workflows resolve PingOne users by email. Verify the target user's primary email in PingOne matches the address passed from Serval tickets or workflows.
  </Accordion>
</AccordionGroup>

***

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