Getting started with PingOne management APIs


Getting started tasks

To begin using the PingOne Management APIs, 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 calls to the PingOne API, you must submit your access token with the request 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 + Application.
  3. Select the Worker application type.
  4. Click Configure.
  5. 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.
  6. Click Save and Close.

The Applications page shows the new application and its client_id (under the application name). Click the Application’s details icon to show the details view. Click the toggle switch to enable the application. Click the Configuration tab to show the client_secret.

To run an API test, you also need the environment ID associated with this application connection. To get your environment ID, in the Admin Console, click Settings, then Environment, then Properties. The Properties page shows the environment ID.

Sample authorization request

The following is a sample authorization request that specifies the client_credentials grant type. 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' \
  --user 'client_id:client_secret' \
  --data 'grant_type=client_credentials'

The values for {environmentId}, 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" : 3600
}

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.

Run an API test

Your PingOne account has at least one defined environment resource. You can use the PingOne APIs to return information about the environment resource associated with your application connection.

The following sample shows the GET /environments/{environmentId} operation to list all environment resources and their attributes. The {environmentId} placeholder in the request URL is the application’s environment ID that you obtained from the Admin Console.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}" \
-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. It also displays the property data for the environment and HAL links to show the related resources associated with the environment.

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
        },
        "organization": {
            "href": "https://api.pingone.com/v1/organizations/4235cade-f281-4a5c-80e1-07b0c1cb3cdb"
        },
        "populations": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/populations"
        },
        "users": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users"
        },
        "applications": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications"
        },
        "activities": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/activities"
        },
        "branding": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/branding"
        },
        "features": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/features"
        },
        "resources": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/resources"
        },
        "scopes": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/scopes"
        },
        "importTasks": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/importTasks"
        },
        "passwordPolicies": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/passwordPolicies"
        },
        "userActivities": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/userActivities"
        },
        "signOnPolicies": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/signOnPolicies"
        },
        "keys": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/keys"
        },
        "templates": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/templates"
        },
        "notificationsSettings": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/notificationsSettings"
        },
        "schemas": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/schemas"
        }
    },
    "id": "88c23def-39c9-4646-8d41-aa91a14a1006",
    "name": "Test Env One",
    "description": "For simulated traffic.",
    "organization": {
        "id": "4235cade-f281-4a5c-80e1-07b0c1cb3cdb"
    },
    "type": "SANDBOX",
    "region": "NA",
    "createdAt": "2018-08-22T01:57:50.079Z",
    "updatedAt": "2018-08-31T17:56:45.074Z"
}

Follow-up activities

For additional hands-on experience with PingOne for Customers API endpoints, see Sample applications and Postman collections. In the PingOne API postman collections section, click the Run in Postman button to download a comprehensive Postman collection that includes all PingOne Authentication and Management API endpoints.

For additional information about PingOne authorization and authentication, see Activity - Authorization and authentication.