Getting started


Getting started tasks

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

  1. Register a client.
  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 clientSecret values needed to request an access token. To make any call to the PingOne API, you must specify your access token for API authentication.

There are two ways to register an application: (1) use the Admin Console, or (2) initiate an API request to the applications service.

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. Click + Application.
  3. For Properties, enter the following information:
  • Application Name. A unique identifier for the client.
  • Description. A brief characterization of the client (optional).
  1. Click Next.
  2. For Category and Identity Type, select one of the following:
  • Mobile. Mobile application. User identity type.
  • Service Account. An account that acts on its own for limited purposes. Client identity type.
  • On-Prem. On-Premise account.
  • Interactive User Application. A UI that users interact with to manage data. User identity type.
  • Third-Party. Third-party application. Client identity type.
  • Other. Other
  • User Identity. The client acts on behalf of a user and has that user’s roles. Client Identity. The client has its own defined roles.
  1. Click Next.
  2. For Authentication and Authorization, select the method that the client should use:
  • OAuth 2 client credentials. Authenticate using credentials, in which the authorization server authenticates the client.
  • OAuth 2 implicit. Authenticate using an implicit grant, in which the client is issued an access token directly. The token is issued based on the resource owner authorization.
  1. Click Done.

Click the icon at the far right of the Application name banner to show the details view. The Profiles tab shows the clientID.

App Connection Profile

Click the Configuration tab to show the clientSecret and the grantType attribute values needed to initiate the client_credentials grant.

App Connection Configuration

Call the Applications service

Doc Note: The Applications service is not complete yet. Update this procedure when it’s ready.

To use the Applications service to create the application connection, perform a POST request to the applications endpoint. Here is a sample:

curl -X POST "https://api.pingone.com/v1/environments/{Id}/applications" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "audiences": [
    "IT"
  ],
  "category": "IT Applications",
  "description": "User Management Client for MyCompany",
  "grantType": "client_credentials",
  "name": "MyCompany User Management Console",
  "state": "enabled"
}"

The values for audiences, category, description, grantType, name, and state represent your organization’s values. Note that this request requires the Environment ID for your PingOne account in the request URL.

The Applications service returns the id and secret in the response body:

{
  ...

  "id": "feff791f-a12f-44ec-a696-53be4ac1f9c2",
  "name": "MyClient",
  "secret": "593307e7-cb0e-4506-a738-bd65fd9c562a",

  ...
}

Acquire an access token

You can acquire an access token by submitting a POST request to the PingOne authentication service.

curl -k -X POST -H "Accept: application/json" -d 'grant_type=client_credentials' -d 'client_id=<yourClientID>' -d 'client_secret=<yourClientSecret>' https://auth.pingone.com/as/token.oauth2

The values for grant_type, client_id, and client_secret are the values you received from your API Client Configuration request.

The response JSON includes the following data.

{
  “access_token”: “jwtToken“,
  "token_type": "Bearer",
  "expires_in": 3599
}

The jwtToken value is the 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 base64url-encoded authentication token as its parameter value.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/flows/{flowId}" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'

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 an authentication flow step, the PATCH operation requires values for attribute values you want to change in the request body:

{
  "action": {
    "id": "8dbbc945-7304-44eb-89c4-18871cca9406",
    "type": "LOGIN"
  }
}

Run the API test

Your PingOne account most likely has at least one defined authentication flow. You can use the PingOne APIs to return information about this authentication flow. You need to include the flow flowId attribute value in the request URL to identify the flow you want to retrieve.

The following sample shows the GET /environments/{environmentId}/flows/{flowId} operation to return information about the specified flow resource.

curl -X GET "https://api.pingone.com/v1/environments/5c5eeef9-a4ff-4eb6-9274-3c38bdd9a429/flows/6f051915-099f-43a3-9c86-beee33e48265" \
-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 shows the information about the specified flow resource.

This GET request does not require a request body.