Work with applications


Applications

Application resources define the connection between PingOne for Customers and the actual application (also known as a client connection). The applications service implements functions to create, read, update, delete, and search for applications resources.

This service also provides endpoints to get an application’s connection settings, such as the application id and secret, which are used to submit an authorization request to the PingOne authorization service.

Note: You need the Client Application Developer role to perform operations on application resources. For more information, see Work with user roles.

Get applications

The GET /environments/{environmentId}/applications endpoint returns a list of all application resources for the specified environment resource.

curl -X "GET" "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications"
        }
    },
    "_embedded": {
        "applications": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/1e894703-52db-41a9-acb8-7bb5afa442ef"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c"
                    },
                    "secret": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/1e894703-52db-41a9-acb8-7bb5afa442ef/secret"
                    },
                    "grants": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/1e894703-52db-41a9-acb8-7bb5afa442ef/grants"
                    },
                    "openidConnect": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/1e894703-52db-41a9-acb8-7bb5afa442ef/client"
                    }
                },
                "name": "Adobe Acrobat",
                "enabled": false,
                "type": "SERVICE",
                "protocol": "OPENID_CONNECT",
                "environment": {
                    "id": "02d37832-476a-431b-8a60-d77cecd7005c"
                },
                "id": "1e894703-52db-41a9-acb8-7bb5afa442ef"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/42077bdc-ce61-4005-950b-4d5a1670db8b"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c"
                    },
                    "secret": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/42077bdc-ce61-4005-950b-4d5a1670db8b/secret"
                    },
                    "grants": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/42077bdc-ce61-4005-950b-4d5a1670db8b/grants"
                    },
                    "openidConnect": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/42077bdc-ce61-4005-950b-4d5a1670db8b/client"
                    }
                },
                "name": "Adobe Connect",
                "enabled": true,
                "type": "SERVICE",
                "protocol": "OPENID_CONNECT",
                "environment": {
                    "id": "02d37832-476a-431b-8a60-d77cecd7005c"
                },
                "id": "42077bdc-ce61-4005-950b-4d5a1670db8b"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/7ce83e9d-fc62-4fae-a62f-86e422e411b6"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c"
                    },
                    "secret": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/7ce83e9d-fc62-4fae-a62f-86e422e411b6/secret"
                    },
                    "grants": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/7ce83e9d-fc62-4fae-a62f-86e422e411b6/grants"
                    },
                    "openidConnect": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/7ce83e9d-fc62-4fae-a62f-86e422e411b6/client"
                    }
                },
                "name": "Safari",
                "enabled": false,
                "type": "SERVICE",
                "protocol": "OPENID_CONNECT",
                "environment": {
                    "id": "02d37832-476a-431b-8a60-d77cecd7005c"
                },
                "id": "7ce83e9d-fc62-4fae-a62f-86e422e411b6"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/df5ee1b0-593c-46a5-a88b-30e2de4b3887"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c"
                    },
                    "secret": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/df5ee1b0-593c-46a5-a88b-30e2de4b3887/secret"
                    },
                    "grants": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/df5ee1b0-593c-46a5-a88b-30e2de4b3887/grants"
                    },
                    "openidConnect": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/df5ee1b0-593c-46a5-a88b-30e2de4b3887/client"
                    }
                },
                "name": "SalesForce",
                "enabled": true,
                "type": "SERVICE",
                "protocol": "OPENID_CONNECT",
                "environment": {
                    "id": "02d37832-476a-431b-8a60-d77cecd7005c"
                },
                "id": "df5ee1b0-593c-46a5-a88b-30e2de4b3887"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/c6edbb84-74f0-45be-ad91-36141f4d0235"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c"
                    },
                    "secret": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/c6edbb84-74f0-45be-ad91-36141f4d0235/secret"
                    },
                    "grants": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/c6edbb84-74f0-45be-ad91-36141f4d0235/grants"
                    },
                    "openidConnect": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/c6edbb84-74f0-45be-ad91-36141f4d0235/client"
                    }
                },
                "name": "WebEx",
                "enabled": true,
                "type": "SERVICE",
                "protocol": "OPENID_CONNECT",
                "environment": {
                    "id": "02d37832-476a-431b-8a60-d77cecd7005c"
                },
                "id": "c6edbb84-74f0-45be-ad91-36141f4d0235"
            }
        ]
    },
    "size": 5
}

To minimize the number of application resources returned in the search, you can apply a filtering expression to fine-tune the response data. For example, to return a list of applications resources that are enabled, you can add a filter to the request URL.

The following sample returns a list of application resources with the enabled attribute value set to true:

curl -X "GET" "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications?filter=enabled%20eq%20%22true%22" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data shows only the application resources with an enabled status of true.

To get data for a single application resource, the GET /environments/{environmentId}/applications/{applicationId} operation returns data only for the application resource with the specified ID.

curl -X GET "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/7ce83e9d-fc62-4fae-a62f-86e422e411b6" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/7ce83e9d-fc62-4fae-a62f-86e422e411b6"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c"
        },
        "secret": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/7ce83e9d-fc62-4fae-a62f-86e422e411b6/secret"
        },
        "openidConnect": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/7ce83e9d-fc62-4fae-a62f-86e422e411b6/client"
        },
        "grants": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/7ce83e9d-fc62-4fae-a62f-86e422e411b6/grants"
        }
    },
    "name": "Safari",
    "enabled": false,
    "type": "SERVICE",
    "environment": {
        "id": "02d37832-476a-431b-8a60-d77cecd7005c"
    },
    "id": "7ce83e9d-fc62-4fae-a62f-86e422e411b6"
}

Add applications

The POST /environments/{environmentId}/applications operation adds a new application resource to the specified environment.

curl -X "POST" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/applications" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "name": "Imaging Services",
  "description": "Digital printing services.",
  "enabled": true,
  "type": "SERVICE",
  "loginPageUrl": "http://example.com",
  "protocol": "OPENID_CONNECT",
  "responseTypes": [
    "TOKEN",
    "ID_TOKEN"
  ],
  "grantTypes": [
    "IMPLICIT",
    "REFRESH_TOKEN"
  ],
  "tokenEndpointAuthMethod": "CLIENT_SECRET_BASIC",
  "postLogoutRedirectUris": [
    "https://example.com"
  ],
  "redirectUris": [
    "http://localhost:3000/response",
    "http://localhost:3000/code/response",
    "https://example.com",
    "https://www.getpostman.com/oauth2/callback"
  ]
}'

In addition to the required name attribute, the request body also specifies a value of “true” for the enabled attribute. All other attribute values are optional for the POST request. If a value is not specified for the enabled attribute, it is set to false by default.

Note: If you set the protocol attribute to OPENID_CONNECT, you must provide values for the following OIDC settings:

  • responseTypes
  • grantTypes
  • tokenEndpointAuthMethod
  • postLogoutRedirectUris
  • redirectUris

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/applications/4d5293f4-08a0-4fc6-a767-bf049230f5fe"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        }
    },
    "name": "Imaging Services",
    "description": "Digital printing services.",
    "enabled": true,
    "type": "SERVICE",
    "loginPageUrl": "http://example.com",
    "protocol": "OPENID_CONNECT",
    "responseTypes": [
      "TOKEN",
      "ID_TOKEN"
    ],
    "grantTypes": [
      "IMPLICIT",
      "REFRESH_TOKEN"
    ],
    "tokenEndpointAuthMethod": "CLIENT_SECRET_BASIC",
    "postLogoutRedirectUris": [
      "https://example.com"
    ],
    "redirectUris": [
      "http://localhost:3000/response",
      "http://localhost:3000/code/response",
      "https://example.com",
      "https://www.getpostman.com/oauth2/callback"
    ]
    "environment": {
        "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
    },
    "id": "4d5293f4-08a0-4fc6-a767-bf049230f5fe"
}

Modify an application

To update a property value associated with a selected application resource, use the PUT /environments/{environmentId}/applications/{userId} operation to modify the specified attribute values. For example, you can change the description attribute value of the application.

curl -X "PUT" "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/applications/4d5293f4-08a0-4fc6-a767-bf049230f5fe" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "description": "Digital printing and document scanning services."
}'

The request body specifies an updated property value for the description attribute to provide additional information about the application.

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/applications/4d5293f4-08a0-4fc6-a767-bf049230f5fe"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        }
    },
    "name": "Imaging Services",
    "description": "Digital printing and document scanning services.",
    "enabled": true,
    "type": "SERVICE",
    "protocol": "OPENID_CONNECT",
    "loginPageUrl": "http://example.com",
    "environment": {
        "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
    },
    "id": "4d5293f4-08a0-4fc6-a767-bf049230f5fe"
}

Get an application secret

An application resource’s secret is a required parameter when you submit a client_credentials request to the PingOne authorization server. The application’s secret attribute value will have a minimum length of 64 characters according to SHA-512 requirements when using the HS512 algorithm to sign ID tokens using the secret as the key.

The GET /environments/{environmentId}/applications/{applicationId}/secret operation returns the specified application resource’s secret attribute.

curl -X GET "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/1e894703-52db-41a9-acb8-7bb5afa442ef/secret" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/applications/4d5293f4-08a0-4fc6-a767-bf049230f5fe/secret"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        },
        "application": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/applications/4d5293f4-08a0-4fc6-a767-bf049230f5fe"
        }
    },
    "environment": {
        "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
    },
    "secret": "l2tO2tfqRWZ~DLZ1Dfi8rptBNgKzcJHtOPiqjJ0iJwaRXufnU5tzR51acNkzl5Hy"
}

Get an application’s connection settings

An application resource’s id is a required parameter when you submit a client_credentials request.

The GET /environments/{environmentId}/applications/{applicationId}/client operation returns the application connection settings for the specified application resource.

curl -X GET "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/1e894703-52db-41a9-acb8-7bb5afa442ef/client" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/applications/4d5293f4-08a0-4fc6-a767-bf049230f5fe/client"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        },
        "application": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/applications/4d5293f4-08a0-4fc6-a767-bf049230f5fe"
        }
    },
    "environment": {
        "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
    },
    "application": {
        "id": "4d5293f4-08a0-4fc6-a767-bf049230f5fe"
    },
    "grantTypes": [
        "CLIENT_CREDENTIALS"
    ],
    "tokenEndpointAuthMethod": "CLIENT_SECRET_BASIC"
}

Update an application’s connection settings

When you update an application resource’s connection settings, you must specify a value for the grantTypes associated with the application. For more information about access grant types, see Getting started.

You must also specify a value for the tokenEndpointAuthMethod attribute, which determines the application authentication method. The application uses the token endpoint to obtain an access token. The tokenEndpointAuthMethod attribute supports the following authentication methods:

  • none

    An authentication method for public applications that do not have a client_secret. This method is often used with the implicit or refresh_token grant types.

  • client_secret_basic

    An authentication method in which an OAuth application uses the HTTP basic authentication scheme to obtain the access token.

  • client_secret_post

    An authentication method in which an OAuth application uses HTTP post authentication scheme to obtain the access token.

Note: The tokenEndpointAuthMethod attribute must not be set to NONE for a client_credentials grant type.

The PUT /environments/{environmentId}/applications/{applicationId}/client operation updates the application connection settings for the specified application resource.

curl -X PUT "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/1e894703-52db-41a9-acb8-7bb5afa442ef/client" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d $'{
  "grantTypes": "refresh_token",
  "tokenEndpointAuthMethod": "none"
}'

The following table shows the relationships between the application type attribute and the default grantTypes, response_type, and tokenEndpointAuthMethod attributes.

Application type Grant type Response type Token endpoint authentication method
Non-interactive client_credentials token client_secret_basic
Native authorization_code, implicit, refresh_token token, id_token, code none
Web authorization_code, refresh_token code client_secret_basic
Single-page implicit token, id_token none

Note: For any application type (except non-interactive), you can specify either none, client_secret_basic, or client_secret_post as the tokenEndpointAuthMethod attribute value. Non-interactive applications use the client_credentials grant type, which does not support a tokenEndpointAuthMethod value of none.

Delete an application

To delete an application resource, you need to specify the environment ID and the application resource ID. The DELETE /environments/{environmentId}/applications/{applicationsId} operation deletes the identified application resource.

curl -X "DELETE" "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/applications/4d5293f4-08a0-4fc6-a767-bf049230f5fe" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

For successful delete operations, a 204 NO CONTENT message is returned by the request.