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 you complete these tasks, you can make any PingOne API calls allowed by the permissions encoded in your access token.

Configure 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. Click Connections.
  2. 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:

  • authorization_code

    An application exchanges an authorization code for an access token.

  • implicit

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

  • refresh_token

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

  • client_credentials

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

Sample authorization request

The following is a sample authorization request that specifies the CLIENT_CREDENTIALS grant type and three scope resources. For this request, the application’s tokenEndpointAuthMethod attribute value must be set to client_secret_post.

curl --request POST \
  --url 'https://auth.pingone.com/{environmentID}/as/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'scope=p1:read:env:user p1:create:env:user p1:read:env:user&grant_type=client_credentials&client_id={applicationID}&client_secret={secret}'

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

Note: For client_credentials requests in which the tokenEndpointAuthMethod attribute value is set to client_secret_basic, the client_id and client_secret attributes cannot be part of the request body. In these cases, the client_id and client_secret are passed in as a Base64 encoded authorization header in the request. For more information, see Application authorization and authentication

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 api.pingone.com. 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 Base64 url-encoded authentication token as its parameter value.

curl -X "POST" "https://api.pingone.com/v1/environments/{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 "https://api.pingone.com/v1/environments" \
-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.