Getting started

Getting started tasks

To begin using the PingOne API, you will need to complete the following tasks:

  1. Configure an application connection using the PingOne Admin Console application.
  2. Acquire an access token.
  3. Test your access token with a simple API request.

After these tasks are completed successfully, you can make any PingOne API calls allowed by the permissions encoded in your access token.

Configuring an application connection

The application connection (also referred to as an API client) contains the clientId and client_secret property values needed to request an access token. To make any call to the PingOne API, you must specify your access token for API authentication.

To acquire an access token use the Admin Console to configure your first application connection.

Use the Admin Console

PingOne administrators can use the PingOne for Customers Admin Console to add an application connection. To create the application connection:

  1. On the top of the page, click Connections.
  2. On the left, click Applications.
  3. Click + Application.
  4. Select the Non-interactive. application type.
  5. Click Next.
  6. Create the application profile by entering the following information:
    • Application name. A unique identifier for the application.
    • Description (optional). A brief characterization of the application.
    • Icon (optional). A pictorial representation of the application. Use a file up to 1MB in JPG, JPEG, GIF, or PNG format.
  7. Click Next.
  8. Grant access to the application by selecting the OAuth scopes for the application. The OAuth scopes determine the resources that the application can access. Click and drag scopes in the left column to add them to the scope grants column on the right. (Make sure you add the read environment p1:read:env:environment scope, which is needed for the API request to test your access token.)
  9. Click Save and Close.

Click the icon at the far right of the Application name banner to show the details view. The Profiles tab shows the clientID. Click the Configuration tab to show the client_secret value needed to initiate the client_credentials grant.

Acquire an access token

You can acquire an access token by submitting a POST request to the PingOne authentication service. PingOne supports several OAuth 2.0 grant types:


    An application exchanges an authorization code for an access token.


    An access token is issued without requiring an authorization code exchange.


    A refresh token is exchanged for an access token after the access token has expired.


    The application obtains an access token to access its own resources.

A valid authorization request returns an access token along with additional information in the response, including a response_type attribute. The following is the list of the OAuth 2.0 response types supported by the PingOne authorization server:

  • CODE

    If the grant type is AUTHORIZATION_CODE, the response_type attribute must have the CODE value.


    If the grant type is IMPLICIT, the response_type attribute must have the ID_TOKEN or the TOKEN value.

Note: The tokenEndpointAuthMethod attribute must not be set to a value of NONE for a CLIENT_CREDENTIALS grant type. Also note that the offline_access scope is valid only for the REFRESH_TOKEN grant type. When configuring an internal client (as shown in the example above), the grant type must be a CLIENT_CREDENTIALS grant, and the response_type must have a value of TOKEN.

Sample authorization request

The following is a sample authorization request that specifies the CLIENT_CREDENTIALS grant type. It also specifies three scope resources as parameters to the client_credentials attribute.

curl -k -X POST -H "Accept: application/json" -d 'grant_type=client_credentials&scope=p1:read:env:user p1:create:env:user p1:read:env:userPasswordState' -d 'client_id=my-client-id' -d 'client_secret=76c173fd-f323-2136-b4e6-9d8353d3721b'

Note: The scope resources in the authorization request are separated by spaces.

The values for client_id, and client_secret are the values you received from the application connection configured through the Admin Console.

The response JSON includes the following data.

  “access_token”: “eyJhbGciOiJSUzI1NiIsImtpZCI6InRlc3QifQ.eyJzY29wZSI6IiIsImNsaWVudF9pZCI6ImlkZW50aXR5LW...“,
  "token_type": "Bearer",
  "expires_in": <value>

The access_token value is the encoded Bearer token value that you submit in the header of each API request.

Test your access token

The public endpoint for calling PingOne API services is The following information illustrates how to construct a typical PingOne API request.

Create the API request header

The API request header contains the authentication information you must provide to make a call to any PingOne API resource. The Authorization parameter takes the full bearer token as its value, which contains the authorization information needed to access the requested resource.

The following sample shows the API request header (-H 'Authorization: Bearer) with a base64url-encoded authentication token as its parameter value.

curl -X "POST" "{environmentId}/users" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6InRlc3QifQ.eyJzY29wZSI6IiIsImNsaWVudF9pZCI6ImlkZW50aXR5LW...'

This request header also shows an additional parameter of note:

  • Content-Type

    In the header of a PUT or POST request, this parameter identifies the media type of the request data sent to the server. For most PingOne API calls, the value is application/json.

Create the API request body

The API request body for POST, PATCH, or PUT requests provide the attribute values needed to complete the create or update operation. For example, to update a user’s password, the PUT operation requires values for the currentPassword and newPassword attributes in the request body:

  "currentPassword": "changeme",
  "newPassword": "difPassword123!"

Run an API test

Your PingOne account most likely has at least one defined environment resource. You can use the PingOne APIs to return information about the environment resources associated with your organization. (Requests to retrieve environment resources will succeed only if you included the p1:read:env:environment scope in your authorization request.)

The following sample shows the GET /environments operation to list all environment resources and their attributes.

Note: This sample requires the p1:read:env:environment scope for the client_credentials grant.

curl -X GET "" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

In the request header, the Bearer jwtToken value is your full base64url-encoded token generated by the PingOne authentication service. If your token is valid, the API request returns a 200: Successful operation message, and the response data lists all environment resources associated with your organization, if any are defined.

This GET request does not require a request body.