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
createdAt The time the resource was created.
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 NONE, OPENID_CONNECT, and 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.
updatedAt The time the resource was last updated.
bundleId A string that specifies the bundle associated with the application, for push notifications in native apps. The value of the bundleId property is unique per environment, and once defined, is immutable.
packageName A string that specifies the package name associated with the application, for push notifications in native apps. The value of the packageName property is unique per environment, and once defined, is immutable.

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, refresh_token, 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. The first URL in the list is used as default (there must be at least one URL). This is a required property.
assertionDuration An integer that specifies the assertion validity duration in seconds. This is a required property.
assertionSigned A boolean that specifies whether the SAML assertion itself should be signed. The default value is true.
idpSigning.key.id A string that specifies the certificate to be used by the identity provider to sign assertions and responses. If this property is omitted, the default signing certificate for the environment is used.
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 binding protocol to be used for the logout response. Options are HTTP_REDIRECT or HTTP_POST. The default is HTTP_POST; existing configurations with no data default to HTTP_POST. This is an optional property.
sloEndpoint A string that specifies the logout endpoint URL. This is an optional property. However, if a sloEndpoint logout endpoint URL is not defined, logout actions result in an error.
sloResponseEndpoint A string that specifies the endpoint URL to submit the logout response. If a value is not provided, the sloEndpoint property value is used to submit SLO response.
spEntityId A string that specifies the service provider entity ID used to lookup the application. This is a required property and is unique within the environment.
spVerification.certificates[].id An array that specifies the certificate IDs used to verify the service provider signature.

Applications SAML metadata settings data model

Property Description
acsBindings A string that specifies the assertion consumer service binding protocol. Options are: HTTP_REDIRECT or HTTP_POST
acsUrls A string that specifies the assertion consumer service URLs.
authnRequestsSigned A boolean that specifies whether the SAML authentication request is signed.
encryptionCertificate.pkcs7Der A byte array that specifies the PKCS7 encryption certificate in DER format.
sloBinding A string that specifies the SAML single logout binding protocol used for logout response. Options are: HTTP_REDIRECT or HTTP_POST.
sloEndpoint A string that specifies the SAML single logout endpoint URL. This property is required.
signingCertificates[].pkcs7Der A byte array that specifies the PKCS7 signing certificates in DER format.

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.

The following sample POST operation shows usage of the optional bundleId and packageName properties, for adding a new NATIVE_APP type 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": "NATIVE_APP",
 "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" ],
 "bundleId": "com.pingidentity.bundleId",
 "packageName": "com.pingidentity.packageName"
}'

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

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",
    "sloBinding": "HTTP_POST",
    "sloEndpoint": "https://example.com/slo",
    "sloResponseEndpoint": "https://example.com",
    "responseSigned": true,
    "assertionSigned": true,
    "idpSigning": {
      "key": {
        "id": "{keyID}"
      }
    },
    "spVerification": {
      "cert": {
        "id": "{certID}"
    }
  }
}'

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",
    "sloEndpoint": "https://example.com/slo",
    "sloResponseEndpoint": "https://example.com",
    "responseSigned": true,
    "sloBinding": "HTTP_POST",
    "acsUrls": [
        "https://example.com"
    ],
    "assertionDuration": 60,
    "assertionSigned": true,
    "idpSigning": {
      "key": {
        "id": "{keyID}"
      }
    },
    "spVerification": {
      "cert": {
        "id": "{certID}"
    }
  }
}

Parse SAML application metadata

You can use the POST /environments/{environmentId}/applications endpoint to return SAML application connection property values needed to establish the application connection. The following sample shows how to parse 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 '{
    "<file content as bytes>"
}'

The following sample shows how to return 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+url' \
-H 'Authorization: Bearer jwtToken' \
-d '{
    "<URL>"
}'

The response data looks like this:

{
  "entityId": "http://test.com/validEntityId",
  "acsBinding": "HTTP_POST",
  "acsUrls": [
    "https://test.com/sp/acs"
  ],
  "sloEndpoint": "https://test.com/redirect/slo",
  "sloBinding": "HTTP_REDIRECT",
  "authnRequestsSigned": true,
  "signingCertificates": [
    {
      "pkcs7Der": "MIAGCSqGSIb3DQEHAqCAMIACAQExADCABgkqhkiG9w0BBwEAAKCAMIIigAAMQAAAAAAAAA="
    },
    {
      "pkcs7Der": "MIAGCSqGSIb3DQEHAqCAMIACAQExADCABgkqhkiG9w0BBwEAAKCAMIIDLMt1SW7gZXAAAxAAAAAAAAAA=="
    }
  ],
  "encryptionCertificate": {
    "pkcs7Der": "MIAGCSqGSIb3DQEHAqCAMIACAQExADCAbw48J9rfWP+Kt8BTqoj4HwfG7Dg52LDugAAMQAAAAAAAAA="
  },
  "x509SigningCert": "MIAGCSqGSIb3DQEHAqCAMIAChm3c0oVmN16wWLJBzi6mDqHaYigAAMQAAAAAAAAA=",
  "x509EncryptionCert": "MIAGCSqGSIb3DQEHAqCAMIACAQExg52LDugAAMQAAAAAAAAA="
}

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. The request also requires the name, type, and protocol attributes in the request.

curl -X "PUT" "https://api.pingone.com/v1/{environmentId}/applications/{applicationId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
    "name": "AppName",
    "description": "This is my UPDATED app description",
    "protocol": "OPENID_CONNECT",
    "type": "WEB_APP"
    }'

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/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/d64c5a69-51ed-4c73-b8bc-8a3fafa6d0ea"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
        },
        "secret": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/d64c5a69-51ed-4c73-b8bc-8a3fafa6d0ea/secret"
        },
        "grants": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/d64c5a69-51ed-4c73-b8bc-8a3fafa6d0ea/grants"
        }
    },
    "environment": {
        "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
    },
    "id": "d64c5a69-51ed-4c73-b8bc-8a3fafa6d0ea",
    "name": "AppName",
    "description": "this is my UPDATED app description",
    "enabled": false,
    "type": "WEB_APP",
    "protocol": "OPENID_CONNECT",
    "createdAt": "2019-06-13T19:12:40.321Z",
    "updatedAt": "2019-06-20T18:42:29.265Z"
}

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.