Working with applications


Applications

Applications define the client applications that are allowed to authenticate with the PingOne Platform. 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 Working 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"
                    }
                },
                "name": "Adobe Acrobat",
                "enabled": true,
                "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/c6edbb84-74f0-45be-ad91-36141f4d0235"
                    }
                },
                "name": "WebEx",
                "enabled": false,
                "environment": {
                    "id": "02d37832-476a-431b-8a60-d77cecd7005c"
                },
                "id": "c6edbb84-74f0-45be-ad91-36141f4d0235"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/applications/df5ee1b0-593c-46a5-a88b-30e2de4b3887"
                    }
                },
                "name": "SalesForce",
                "enabled": false,
                "environment": {
                    "id": "02d37832-476a-431b-8a60-d77cecd7005c"
                },
                "id": "df5ee1b0-593c-46a5-a88b-30e2de4b3887"
            }
        ]
    },
    "size": 3
}

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”.

{
    "_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"
                    }
                },
                "name": "Adobe Acrobat",
                "enabled": true,
                "environment": {
                    "id": "02d37832-476a-431b-8a60-d77cecd7005c"
                },
                "id": "1e894703-52db-41a9-acb8-7bb5afa442ef"
            }
        ]
    },
    "size": 1
}

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/1e894703-52db-41a9-acb8-7bb5afa442ef" \
-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/1e894703-52db-41a9-acb8-7bb5afa442ef"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c"
        }
    },
    "name": "Adobe Acrobat",
    "enabled": true,
    "environment": {
        "id": "02d37832-476a-431b-8a60-d77cecd7005c"
    },
    "id": "1e894703-52db-41a9-acb8-7bb5afa442ef"
}

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://wardstreetpress.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 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://wardstreetpress.com",
    "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 PATCH /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 "PATCH" "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",
    "loginPageUrl": "http://wardstreetpress.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 per 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 also 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:

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"
}

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.