Grants service


Grants

Grants allow you to assign scopes to an application. For example, a request to the POST /environments/{envId}/applications/{appId}/grants endpoint specifies the application ID in the request URL, which designates the application to which the resource access grant is applied. The request body specifies the resource ID (the resource associated with the application) and the list of scope IDs to associate with the application.

Important: If you do not assign at least one scope to your application through a resource access grant, the application cannot access any resources. Furthermore, its client_id and client_secret property values cannot be used to generate access tokens for the application.

Grants API operations

The grants service supports the following endpoint operations:

For hands-on experience with the grants 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.

Grants data model

Property Description
application.id A string that specifies the application resource’s unique identifier associated with the grant.
createdAt The time the resource was created.
environment.id A string that specifies the environment resource’s unique identifier associated with the grant.
id A string that specifies the resource’s unique identifier.
resource.id A string that specifies the resource entity’s unique identifier associated with the grant.
scopes An array of scopes associated with the grant.
updatedAt The time the resource was last updated.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request was invalid.
401 You weren’t authenticated to perform this operation.
404 The specified object doesn’t exist.

Endpoint examples

Get grants

The GET /environments/{environmentId}/resources/{resourceId}/grants endpoint returns a list of all grants associated with the specified application resource.

curl -X "GET" "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/applications/4d5293f4-08a0-4fc6-a767-bf049230f5fe/grants" \
-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/grants"
        }
    },
    "_embedded": {
        "grants": []
    },
    "count": 0,
    "size": 0
}

Get one grant

To get data for a single grant associated with a specified application resource, the GET /environments/{environmentId}/resources/{resourceId}/grants/{grantId} operation returns data for the grant resource ID specified in the request URL.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/resources/{resourceId}/grants/{grantId}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

Create grants

The following sample shows the POST /environments/{environmentId}/resources/{resourceId}/grants operation to assign scopes to an application.

Note: You can call GET /environments/{envId}/resources to get a list of resource IDs associated with the specified environment. In addition, you can call GET /environments/{envId}/scopes to get a list of scope IDs for the specified environment.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/resources/{resourceId}/grants" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
    "resource": {
        "id": "{resourceID}"
    },
    "scopes": [
        "{scopeID}"
    ]
}'

Note: When making an OAuth request, only self scopes are included in the access token when using the IMPLICIT or AUTHORIZATION_CODE grant types (for example, p1:read:self:user and p1:update:self:user). Only the environment scopes (non self scopes) are included in the access token when using the CLIENT_CREDENTIALS grant type. For more information about grant types, see Getting started.

Update grants

The following sample shows the PUT /environments/{envId}/resources/{resId}/grants/{grantId} operation to assign scopes to an application.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/resources/{resourceId}/grants/{grantId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
    "resource": {
        "id": "{resourceID}"
    },
    "scopes": [
        "{scopeID}"
    ]
}'

Delete grants

The following sample shows the DELETE https://api.pingone.com/v1/environments/{environmentId}/resources/{resourceId}/grants/{grantId} operation to delete the grant from the specified environment.

curl -X DELETE "https://api.pingone.com/v1/environments/{environmentId}/resources/{resourceId}/grants/{grantId}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \

When successful, the DELETE request returns a code 204 No Content message.