PingOne Advanced Services

Using the PingOne Advanced Services administrative API

PingOne Advanced Services includes a REST-based API for administrative functions. The administrative API provides a programmatic way to make configuration changes to PingOne Advanced Services, as opposed to submitting a service request.

For example, you can create and update virtual hosts yourself through the administrative API. Learn more about virtual hosts in Creating and updating virtual hosts.

Before users can access the API, ensure that they have the appropriate roles assigned. Learn more about this process in Configuring access to the administrative API.

Interactive documentation is also available to explore the API endpoints, view documentation for the API, and experiment with API calls. You can make API calls from an interactive user interface, custom applications, or from command-line tools.

Learn more:

All administrative API events are logged. These logs include information about each event, the date and time it occurred, and information that identifies the users involved. Learn more about event logs in Monitoring and logging.

Configuring access to the administrative API

The API requires a JWT Bearer token for authenticating requests. This token can be retrieved using either an authorization code flow or a client credentials flow.

Authenticate using an authorization code flow

The API supports the authorization code flow, which gets access tokens by securely redirecting users to the authorization server for authentication.

To set this up, you’ll need to:

  1. Ensure users are assigned the appropriate PingOne Advanced Services user access control roles.

  2. Sign on to an application to get an access token.

  3. Use the token to authenticate and access the API using Swagger UI, or command-line tools, such as Postman or cURL.

Assigning users the appropriate roles

If you’re using the PingOne Platform:

  1. In the user profile, add a custom attribute. Learn more about adding these attributes in Add custom attributes to a user in the PingOne documentation.

  2. Select the appropriate PingOne Advanced Services roles for the user and click Save. You can find a complete list of available roles in User access control roles.

If you’re using the CAP, Ping Identity manages the roles and permissions your administrators are assigned. Submit an Elevate Admin service request and specify which roles and permissions users should have.

Signing on to an application to get an access token

  1. Go to the PingOne Advanced Services login URL:

    https://self-service-api.<environment>-<customer>.<region>.ping.cloud/api/v1/auth/login/{application}

    Valid values for the application are “self-service”, “PingAccess”, “pingfederate”, “opensearch”, and “argocd”.

  2. Enter your credentials and click Submit.

    If authentication is successful, you’re redirected to the Success page and a Copy Token button displays.

  3. Click Copy Token to copy the token to your clipboard.

Using the token to authenticate

If you’re using the API interactive documentation:

  1. Go to the respective API docs URL.

  2. Click Authorize.

  3. Paste the token into the input field and click Authorize and then Close.

    All requests made from the interactive documentation will be authenticated.

If you’re using command-line tools, such as Postman or cURL, query the API directly and include the bearer token in the headers.

Example

{"Authorization": "Bearer {TOKEN}"}

Authenticate using a client credentials flow

This API also supports the client credentials flow, which is designed for machine-to-machine (M2M) interactions, where an application needs to access resources without involving a user.

This type of flow can only be used if your PingOne environment is connected to your PingOne Advanced Services environment and both are correctly configured.

To set this up, you’ll need to:

  1. Create an OIDC application.

  2. Generate a token.

To ensure that only administrators can generate access tokens, restrict access to the application that you created. Learn more about this process in Restricting access to the application.

Creating an OIDC application

Start by creating an OpenID Connect (OIDC) application in PingOne.

  1. Go to Applications > Resources.

  2. Click the icon.

  3. Create the resource by completing these fields:

    • Resource name: A unique identifier for the resource.

    • Description (optional): A brief characterization of the resource that helps identify it.

  4. Click Next.

  5. On the Attributes page, click Add to add a new attribute.

  6. Name the new attribute groups.

    Enter the appropriate user access control roles.

    Set the values to a hardcoded list of valid roles. For example, {“dev-tls-admin”, “prod-tls-audit”}. Learn more about these roles and permissions in User access control roles.

    The PingOne Advanced Services attributes must be set up for them to display in the list. Learn more about adding this attribute in Creating custom user attributes.

  7. Click Next.

  8. On the Scopes page, add a new scope to map the PingAccess role to the new application. Click Add Scope and complete the following fields:

    • Scope name: A unique identifier for the scope.

    • Description (optional): A brief description of the scope that helps identify it.

  9. Click Save.

  10. Now, add the OIDC application. Go to Applications > Applications.

  11. Click the icon.

  12. Complete the following fields:

    • Application name: A unique identifier for the application.

    • Description (optional): A brief characterization of the application that helps identify it.

    • Icon (optional): A graphic representation of the application. Use a file up to 1 MB in JPG, JPEG, GIF, or PNG format.

  13. In the list of available application types, select OIDC Web App. Click Save.

  14. On the Configuration tab, click the Pencil icon to edit the configuration.

    • Change the Response Type to none by clearing all the options.

    • Change the Grant Type to Client Credentials.

  15. Click Save.

  16. On the Resources tab, click the Pencil icon to add the scope you added in step 8 to the application.

  17. Click Save and click the toggle at the top of the details panel to enable the application.

Generating a token

Access the new application in the PingOne admin console to generate an access token.

  1. Follow the steps outlined in Getting an access token in the PingOne documentation.

  2. Include the bearer token in the headers.

    Example
    {"Authorization": "Bearer {TOKEN}"}

Restricting access to the application

To ensure that only administrators can generate access tokens, restrict access to the application that you created.

Steps

  1. Select the application, click the Access tab, and then the Pencil icon.

  2. Select the Admin Only Access checkbox and click Save.

Using the API interactive documentation

The API includes interactive documentation for both developers and non-developers to explore the API endpoints, view documentation for the API, and experiment with API calls. Built on Swagger UI, this interactive tool makes it easy for you to visualize, interact with, and test the APIs within a browser.

You can make API calls from an interactive user interface, custom applications, or from command line tools such as cURL.

To access the administrative API documentation:

  1. Start a web browser.

  2. Browse to the URL:

    https://self-service-api.<environment>-<customer>.<region>.ping.cloud/docs
    The API is also documented in the OpenAPI Specification, previously known as the Swagger Specification. Go to: 
    https://self-service-api.<environment>-<customer>.<region>.ping.cloud/api/v1/openapi.json

To test an administrative API:

  1. Select a section of the administrative API you would like to explore. For example, /hostnames.

  2. Expand the method you want to use. For example, GET /hostnames.

  3. Enter required parameters, if any. For more information, see Schema Models under the selected API endpoint.

  4. Click Try it out.

    You will be prompted to sign on using an access token for OAuth authentication. The role assigned to the respective administrative accounts affects the access to the requested API.

    If the request completes successfully, the administrative API returns the Request URL, the Response Body, the Response Code, and the Response Headers.