Application Access to APIs: Client Grants

In Auth0, you can control how applications access your APIs using application API access policies and client grants. 

A client grant provides fine-grained application access to an API. It associates:

• An API identified by its audience or unique identifier. 

• An application identified by its client_id. 

• A list of permissions such as scopes and/or authorization_details_types that the application is allowed to request for the specified audience.

To learn more about the list of attributes you can define in a client grant, read Client grant attributes. To learn how to define and manage client grants, read Configure client grants.

When you configure an API's application access policy to require_client_grant, only applications with a client grant defined can get an access token for the API. The client grant establishes the maximum permissions an application can request from the API by following the least privilege principle approach. As a result, Auth0 recommends using require_client_grant when configuring an API’s application access policy.

To illustrate how client grants follow the least privilege principle approach, say you have a Social Media API with the permissions: read:posts, write:posts, read:friends, and delete:posts. You create an application and define a client grant with the permissions: read:posts and write:posts.

This client grant now serves as a hard ceiling. Even though the Social Media API has other permissions, your application can never request or be granted read:friends or delete:posts.

In user access and client access flows, client grants define the final set of permissions that control an application’s access to an API. The client grant’s subject_type attribute determines the type of application access allowed for an API.

An application can have up to two client grants for a single API:

• When you set subject_type to client, you define its machine-to-machine permissions.

• When you set subject_type to user, you define its permissions to act on the user’s behalf.

The following table explains how client grants control application access to APIs based on the access type flow: 

A client grant has several attributes that you can define to configure application access to APIs:

You can use the Management API to configure client grants via the /client-grants endpoint.

To create a new client grant, make a POST request to the /client-grants endpoint.

The following code sample creates a client grant for an application to access the https://api.my-service.com API. The subject_type is user, which means the client grant is for user access, and allows the application to request the read:item scope and the payment authorization details type.

curl --location 'https://{yourDomain}/api/v2/client-grants' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
--data '{
    "client_id": "{CLIENT_ID}",
    "audience": "https://api.my-service.com",
    "scope": [
        "read:item"
    ],
    "authorization_details_types":["payment"],
    "subject_type": "user"
}'

To update an existing client grant, make a PATCH request to /client-grants/{id}.

The following code sample updates an existing client grant to expand its permissions. The application can now also request the update:item scope and an additional credits_transfer authorization details type.

curl --location --request PATCH 'https://{yourDomain}/api/v2/client-grants/{CLIENT_GRANT_ID}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
--data '{
    "scope": [
        "read:item",
        "update:item"
    ],
    "authorization_details_types":["payment", "credits_transfer"]
}'

To delete a client grant, make a DELETE request to /client-grants/{id}.

The following code sample removes the client grant which revokes the application's access to the API:

curl --location --request DELETE 'https://{yourDomain}/api/v2/client-grants/{CLIENT_GRANT_ID}' \
--header 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}'

You can also query and paginate through the client-grants collections by using parameters like client_id, audience, or subject_type.

The following code sample retrieves all client grants that allow for user access to the https://api.my-service.com API.

curl --request GET \
--url 'https://{yourDomain}/api/v2/client-grants?subject_type=user&audience=https%3A%2F%2Fapi.my-service.com' \
--header 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
--header 'Accept: application/json'

• API Access Policies for Applications
• Application Grant Types