Applications


Applications management

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.

Applications API operations

The Applications endpoints support the following operations:

For hands-on experience with the Applications API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Applications data model

Property Description
description A string that specifies the description of the application.
enabled A string that specifies the current enabled state of the application. Options are ENABLED or DISABLED.
environment A string that specifies the environment associated with the application.
icon The HREF and the ID for the application icon.
id A string that specifies the application ID.
loginPageUrl A string that specifies the custom login page URL for the application.
name A string that specifies the name of the application. This is a required property.
protocol A string that specifies the protocol for the Application. Options are OPENID_CONNECT or SAML.
type A string that specifies the type associated with the application. This is a required property. Options are WEB_APP, NATIVE_APP, SINGLE_PAGE_APP, and WORKER.

Applications OIDC settings data model

Property Description
grantTypes A string that specifies the grant type for the authorization request. This is a required property. Options are authorization_code, implicit, and client_credentials.
homePageUrl A string that specifies the custom home page URL for the application.
postLogoutRedirectUris A string that specifies the URLs that the browser can be redirected to after logout.
redirectUris A string that specifies the callback URI for the authentication response.
responseTypes A string that specifies the code or token type returned by an authorization request. Options are TOKEN, ID_TOKEN, and CODE.
tokenEndpointAuthMethod A string that specifies the client authentication methods supported by the token endpoint. This is a required property. Options are NONE, CLIENT_SECRET_BASIC, and CLIENT_SECRET_POST.

Applications SAML settings data model

Property Description
acsUrls A string that specifies the assertion consumer service URLs.
assertionDuration An integer that specifies the maximum amount of time that an assertion is valid.
assertionSigned A boolean that specifies whether the SAML assertion should be signed. The default value is True.
idpSigning.key The certificate used by the identity provider to sign assertions or responses. If omitted, the default signing certificate for the environment is used.
idpSigning.key.id A string that specifies the certificate ID used by the identity provider to sign assertions or responses.
name A string that specifies the name of SAML attribute and must be unique within an application. The samlAssertion.subject name is a reserved case-insensitive name which indicates the mapping to be used for the subject in an assertion. This is a required property.
required A boolean that indicates if the attribute is mandatory to include the attribute in SAML assertion response. If true, and the attribute does have a value when building the assertion, the SSO flow will fail.
responseSigned A boolean that specifies whether the SAML assertion response itself should be signed. The default value is False.
sloBinding A string that specifies the SAML single logout binding protocol used for logout response. Opotions are: HTTP_REDIRECT or HTTP_POST.
sloEndpoint A string that specifies the SAML single logout endpoint URL. This property is required.
sloResponseEndpoint A string that specifies the single logout response URL. This property is optional.
spEntityId A string that specifies the service provider’s entity ID.
spVerification.cert The certificate used to verify the service provider.
spVerification.cert.id A string that specifies the service provider’s certificate ID.
value A string that specifies the string constants or expression for mapping the attribute path against a specific source. The expression format is: ${.<attribute_path>}. The only supported source is user (for example, ${user.id}). This is a required property.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request could not be completed.
401 You do not have access to this resource.
403 You do not have permissions or are not licensed to make this request.
404 The requested resource was not found.
500 An unexpected error occurred.

Note: You need the Client Application Developer role to perform operations on application resources.

Endpoint examples

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/{environmentId}/applications" \
-H 'Authorization: Bearer jwtToken'

The response returns data for all applications in the environment.

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications"
        }
    },
    "_embedded": {
        "applications": [
            {
                "_links": {
                    "grants": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/cf12be70-c56d-45b6-b45a-956cfbf7fc6c/grants"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
                    },
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/cf12be70-c56d-45b6-b45a-956cfbf7fc6c"
                    },
                    "secret": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/cf12be70-c56d-45b6-b45a-956cfbf7fc6c/secret"
                    },
                    "roleAssignments": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/cf12be70-c56d-45b6-b45a-956cfbf7fc6c/roleAssignments"
                    }
                },
                "environment": {
                    "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
                },
                "id": "cf12be70-c56d-45b6-b45a-956cfbf7fc6c",
                "name": "HR_APP",
                "description": "My HR application.",
                "enabled": true,
                "type": "WORKER",
                "loginPageUrl": "http://example.com",
                "protocol": "OPENID_CONNECT",
                "createdAt": "2019-03-15T17:32:26.817Z",
                "updatedAt": "2019-03-15T17:32:26.817Z",
                "responseTypes": [
                    "TOKEN"
                ],
                "grantTypes": [
                    "IMPLICIT"
                ],
                "tokenEndpointAuthMethod": "CLIENT_SECRET_BASIC",
                "postLogoutRedirectUris": [
                    "https://example.com"
                ],
                "redirectUris": [
                    "https://example.com:3000/code/response",
                    "https://example.com",
                    "https://example.com:3000/response"
                ]
            },
            {
                "_links": {
                    "grants": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/7780e320-fe08-403b-96b0-9f5d57e1ad07/grants"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
                    },
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/7780e320-fe08-403b-96b0-9f5d57e1ad07"
                    },
                    "secret": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/7780e320-fe08-403b-96b0-9f5d57e1ad07/secret"
                    },
                    "roleAssignments": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/7780e320-fe08-403b-96b0-9f5d57e1ad07/roleAssignments"
                    }
                },
                "environment": {
                    "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
                },
                "id": "7780e320-fe08-403b-96b0-9f5d57e1ad07",
                "name": "ACCOUNTING_APP",
                "description": "Description for my accounting application.",
                "enabled": false,
                "type": "WORKER",
                "loginPageUrl": "http://example.com",
                "protocol": "OPENID_CONNECT",
                "createdAt": "2019-03-20T23:08:01.049Z",
                "updatedAt": "2019-03-20T23:08:01.049Z",
                "responseTypes": [
                    "ID_TOKEN",
                    "TOKEN"
                ],
                "grantTypes": [
                    "IMPLICIT"
                ],
                "tokenEndpointAuthMethod": "CLIENT_SECRET_BASIC",
                "postLogoutRedirectUris": [
                    "https://example.com"
                ],
                "redirectUris": [
                    "https://example.com:3000/code/response",
                    "https://example.com",
                    "https://example.com:3000/response"
                ]
            },
    "size": 2
}

Get one application

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/{environmentId}/applications/{applicationId}" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/cf12be70-c56d-45b6-b45a-956cfbf7fc6c"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
        },
        "secret": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/cf12be70-c56d-45b6-b45a-956cfbf7fc6c/secret"
        },
        "grants": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/cf12be70-c56d-45b6-b45a-956cfbf7fc6c/grants"
        },
        "roleAssignments": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/cf12be70-c56d-45b6-b45a-956cfbf7fc6c/roleAssignments"
        }
    },
    "environment": {
        "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
    },
    "id": "cf12be70-c56d-45b6-b45a-956cfbf7fc6c",
    "name": "ACCOUNTING_APP",
    "description": "My accounting application.",
    "enabled": true,
    "type": "WORKER",
    "loginPageUrl": "http://example.com",
    "protocol": "OPENID_CONNECT",
    "createdAt": "2019-03-15T17:32:26.817Z",
    "updatedAt": "2019-03-15T17:32:26.817Z",
    "responseTypes": [
        "TOKEN"
    ],
    "grantTypes": [
        "IMPLICIT"
    ],
    "tokenEndpointAuthMethod": "CLIENT_SECRET_BASIC",
    "postLogoutRedirectUris": [
        "https://example.com"
    ],
    "redirectUris": [
        "https://example.com:3000/code/response",
        "https://example.com",
        "https://example.com:3000/response"
    ]
}

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/{environmentId}/applications" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
  "name": "SALES APPLICATION",
  "description": "Description for my sales application.",
  "enabled": true,
  "type": "WORKER",
  "loginPageUrl": "http://example.com",
  "protocol": "OPENID_CONNECT",
  "responseTypes": [
    "TOKEN",
    "ID_TOKEN"
  ],
  "grantTypes": [
    "IMPLICIT"
  ],
  "tokenEndpointAuthMethod": "CLIENT_SECRET_BASIC",
  "postLogoutRedirectUris": [
    "https://example.com"
  ],
  "redirectUris": [
    "https://example.com:3000/response",
    "https://example.com:3000/code/response",
    "https://example.com"
  ]
}'

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.

OpenID Connect applications

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/88c23def-39c9-4646-8d41-aa91a14a1006/applications/7780e320-fe08-403b-96b0-9f5d57e1ad07"
       },
       "environment": {
           "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
       },
       "secret": {
           "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/7780e320-fe08-403b-96b0-9f5d57e1ad07/secret"
       },
       "grants": {
           "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/7780e320-fe08-403b-96b0-9f5d57e1ad07/grants"
       },
       "roleAssignments": {
           "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/7780e320-fe08-403b-96b0-9f5d57e1ad07/roleAssignments"
       }
   },
   "environment": {
       "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
   },
   "id": "7780e320-fe08-403b-96b0-9f5d57e1ad07",
   "name": "SALES APPLICATION",
   "description": "Description for my sales application.",
   "enabled": true,
   "type": "WORKER",
   "loginPageUrl": "http://example.com",
   "protocol": "OPENID_CONNECT",
   "createdAt": "2019-03-20T23:08:01.049Z",
   "updatedAt": "2019-03-20T23:08:01.049Z",
   "responseTypes": [
       "ID_TOKEN",
       "TOKEN"
   ],
   "grantTypes": [
       "IMPLICIT"
   ],
   "tokenEndpointAuthMethod": "CLIENT_SECRET_BASIC",
   "postLogoutRedirectUris": [
       "https://example.com"
   ],
   "redirectUris": [
       "https://example.com:3000/code/response",
       "https://example.com",
       "https://example.com:3000/response"
   ]
}

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 TOKEN, ID_TOKEN, CODE NONE
Web AUTHORIZATION_CODE 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.

SAML applications

If you set the protocol attribute to SAML, you must provide values for the following SAML settings:

  • spEntityId
  • acsUrls
  • assertionDuration
  • sloEndpoint (optional)
  • sloResponseEndpoint (optional)

The request looks like this:

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/applications" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
    "name": "app_1555021123",
    "description": "this is my application",
    "enabled": true,
    "loginPageUrl": "https://example.com",
    "type": "WEB_APP",
    "protocol": "SAML",
    "assertionDuration": 60,
    "acsUrls": [
        "https://example.com"
    ],
    "sloResponseEndpoint": "https://example.com/SLOServiceResponse.php",
    "spEntityId": "test"
}'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/37c7a13a-bfb4-4eff-9f4c-d7812d642714"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
        },
        "attributes": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/applications/37c7a13a-bfb4-4eff-9f4c-d7812d642714/attributes"
        }
    },
    "environment": {
        "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
    },
    "id": "37c7a13a-bfb4-4eff-9f4c-d7812d642714",
    "name": "app_1555021123",
    "description": "this is my application",
    "enabled": true,
    "type": "WEB_APP",
    "protocol": "SAML",
    "createdAt": "2019-04-11T22:18:43.313Z",
    "updatedAt": "2019-04-11T22:18:43.313Z",
    "spEntityId": "test",
    "sloResponseEndpoint": "https://example.com",
    "responseSigned": false,
    "sloBinding": "HTTP_POST",
    "acsUrls": [
        "https://example.com"
    ],
    "assertionDuration": 60,
    "assertionSigned": true
}

SAML application metadata import

You can use the POST /environments/{environmentId}/applications endpoint to import the SAML application connection metadata needed to establish the application connection. The following sample shows how to import application connection metadata from a file. This operation uses the application/samlmetadata+xml media type as the content type in the request header. The request body specifies the metadata file:

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/applications" \
-H 'Content-type: application/samlmetadata+xml' \
-H 'Authorization: Bearer jwtToken' \
-d '{
    "<filename>"
}'

The following sample shows how to import application connection metadata from a URL. This operation uses the application/samlmetadata+url media type as the content type in the request header. The request body specifies the URL:

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/applications" \
-H 'Content-type: application/samlmetadata+xml' \
-H 'Authorization: Bearer jwtToken' \
-d '{
    "<URL>"
}'

The response data looks like this:

{
    "entityId": "http://adfs.mem-ins.com/adfs/services/trust",
    "acsBinding": "HTTP_POST",
    "acsUrls": [
        "https://adfs.mem-ins.com/adfs/ls/"
    ],
    "sloEndpoint": "https://adfs.mem-ins.com/adfs/ls/",
    "sloBinding": "HTTP_REDIRECT",
    "authnRequestsSigned": false,
    "x509SigningCert": "MIAGCSqGSIb3DQEHAqCAMIACAQExADCAB...",
    "x509EncryptionCert": "MIAGCSqGSIb3DQEHAqCAMIACAQExADCABgkqhki..."
}

Update applications

To update a property value associated with a selected application resource, use the PUT /environments/{environmentId}/applications/{applicationId} 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/{environmentId}/applications/{applicationId}" \
-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": "NATIVE_APP",
    "loginPageUrl": "http://example.com",
    "protocol": "OPENID_CONNECT",
    "responseTypes": [
      "TOKEN",
      "ID_TOKEN"
    ],
    "grantTypes": [
      "IMPLICIT"
    ],
    "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"
}

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/{applicationId} operation deletes the identified application resource.

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

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