The administrator discovery API facilitates global discovery of an administrator’s home environment before forwarding the administrator there to authenticate. The discovery flow inserts screens in the sign-on flow so that discovery occurs before authentication. For example, the flow prompts the user to enter a username, and the API uses the PingOne identity registry to determine the administrator’s home environment (the environment in which their credentials exist) based on the submitted username value.

There is also an administrator discovery indexing service that maintains the relationship between all administrators in PingOne and their home environments. This service is available to multiple workflows to determine username and email uniqueness across the platform.

There are two ways that an administrator can sign on the platform:

  1. Direct to an environment using a deep link that includes the administrator’s home environment identifier in the URL (similar to the current login link provided in the PingOne welcome email).

  2. Through discovery, using discovery-based sign on from console.pingone.com that searches the identity registry to direct the user to the appropriate home environment.

For discovery, if the username exists in multiple environments, the sign-on flow provides an environment chooser that allows the user to select from a list of previously-authenticated environments. After discovery, the flow redirects the user to the login page for the chosen environment. The normal authentication flow for the chosen environment begins, using a login_hint to provide the username.

Discovery flow data model

Property Type Required? Mutable? Description
captcha String Optional Mutable A string that specifies a valid CAPTCHA ID.
environment.id UUID Optional Mutable A string that specifies an environment ID associated with the user.
username String Required Mutable A string that specifies the username of the user.

Discovery index data model

Property Type Required? Mutable? Description
username String Required Mutable A string that specifies the username of the user.
environments[] Array Required Mutable An array that specifies the environment attributes, including ID, region, name, and associated organization ID.
environments[].id UUID Required Mutable A string that specifies the environment ID associated with the user.
environments[].region Array Required Mutable An array of strings that specifies the environment IDs associated with the user.
environments[].name String Optional Mutable A string that specifies an environment ID associated with the user.
environments[].organization.id UUID Required Mutable A string that specifies the organization ID associated with the user.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request could not be completed.
401 You do not have access to this resource.
404 The requested resource was not found.