Skip to main content

​
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

CapabilityDescription
MFA Management bundlePrebuilt 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 requestTyped MFA operations from the hand-authored PingOne MFA spec.
PingOne API discoveryFull 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.
1

Open the PingOne admin console

Sign in to the PingOne admin console for your organization.
2

Copy the Environment ID

Go to Settings → Environment Properties and copy the Environment ID (a UUID).
3

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

Copy the Client ID and Client Secret

From the worker application’s Overview tab, copy the Client ID and Client Secret.
5

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).
Worker applications are machine credentials with broad API access. Restrict the application’s roles to the smallest set that covers your Serval workflows.

​
Connect in Serval

1

Open the PingID connect form

In Serval, add the PingID integration. It is labeled Beta.
2

Region (required)

Select the PingOne API domain for your environment.
3

Environment ID (required)

Paste the UUID from Environment Properties.
4

Client ID (required)

Paste the worker application’s Client ID.
5

Client Secret (required)

Paste the worker application’s Client Secret in the password field.
6

Save and verify

Submit the form. Serval runs three health checks (below).
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.

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

​
Gotchas and troubleshooting

Serval uses the client-credentials grant. Browser-based or authorization-code applications will not exchange tokens the way this integration expects.
A North America Client ID against an EU environment (or mismatched Environment ID) fails token exchange before any MFA workflow runs.
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.
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.
Need help? Contact support@serval.com for assistance with your PingID integration.