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. Get the application’s access token (a JSON Web Token).
  3. Use the access token to run 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. For general information about PingOne APIs, see Management APIs Overview and Authentication APIs Overview.

Configure an application connection

Application connections determine how PingOne for Customers integrates with client applications. When you define the application connection, you also define the application’s access to PingOne resources, which are encoded in the application’s access token. To make calls to the PingOne API, you must submit your access token with the API request.

To acquire an access token, you can use the Admin Console to configure your first 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. To view the application’s access token, you must enable the new application:

  • Click the enable/disable button at the right. The toggle switch shows green to indicate that the new application is enabled.

To get the access token:

  1. Click the application’s details icon (located to the right of the enable/disable button).
  2. Click the Configuration tab.
  3. Click Get Access Token.
  4. From the Access Token window, click Copy Access Token to copy the access token.

To get your environment ID from the Admin Console:

  1. Click Settings.
  2. Click Environment.
  3. Click Properties.

The Properties page shows the environment ID.

Test your access token

The public endpoint for calling PingOne API services for environments in the North America region is api.pingone.com, for environments in the European Union region, the public endpoint is api.pingone.eu, and for environments in the Asia-Pacific region, the public endpoint is api.pingone.asia. 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 show the properties of the specified environment resource. The {environmentId} placeholder in the request URL is the application’s environment ID that you obtained from the Admin Console.

In the North America (NA) region:

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}" \
-H "Authorization: Bearer jwtToken"

In the European Union (EU) region:

curl -X GET "https://api.pingone.eu/v1/environments/{environmentId}" \
-H "Authorization: Bearer jwtToken"

In the Asia-Pacific (AP) region:

curl -X GET "https://api.pingone.asia/v1/environments/{environmentId}" \
-H "Authorization: Bearer jwtToken"

The jwtToken value is your full base64url-encoded access 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 Authentication workflow walkthrough and Authorization and authentication by application type.