Application Access to APIs: Client Grants

Learn about 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 Create client grant.

Application API access policies and 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.

Example: Social Media API

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.

User-delegated access vs. client access

In user and client access, 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:

Access type	subject_type attribute	Description
Client credential access (Machine-to-machine access)	Set subject_type to client.	The client grant directly authorizes the application to access the API on its own behalf instead of the end user’s behalf. The permissions you define in the client grant are the ones the application is authorized to receive in the access token.
User-delegated access	Set subject_type to user.	The client grant defines the maximum permissions the application can request from the API. The final permissions in the access token issued to the application on the user’s behalf are the intersection of the permissions: Requested by the application Allowed by the client grant Allowed by Role-Based Access Control policies for the user Consented to by the end user, if applicable. To learn more about user-delegated access flows, read Authentication and Authorization Flows. User-delegated access flows do not include the Client Credentials Flow.

You can modify the final scopes granted by the authorization server to the application or user using Actions.

Client grant attributes

A client grant has several attributes that you can define to configure application access to APIs using the Auth0 Management API:

Attribute	Description
id	Unique identifier of the client grant.
audience	Unique identifier of the API the client grant is for.
client_id	The unique ID of the application that is being granted access.
scopes	An array of strings representing the permissions the application can request.
authorization_details_types	An array of strings representing rich authorization data types that the application can request. This attribute can only be specified for user-delegated access flows.
subject_type	The type of application access the client grant allows for: user: used for user-delegated access, which corresponds to all flows that generate a token associated with an end user. client: used for machine access, which corresponds to the Client Credentials Flow.
allow_all_scopes	Boolean. Indicates if all scopes defined on the API are allowed for the application. For the API, future-defined scopes are automatically permitted.
organization_usage	Determines how the application may use Organizations when accessing the API via the Client Credentials Flow. Possible values are: deny, allow, or require. To learn more about the Organization settings, read Organizations for M2M Applications: Define Organization Behavior.
allow_any_organization	Determines whether the application can access any Organization when using the Client Credentials Flow. To learn more about the Organization settings, read Organizations for M2M Applications: Define Organization Behavior.

Create client grant

You can create:

• Per-application permissions: Apply granular permissions to each application in your tenant.
• Default permissions for third-party applications: Apply default permissions to all third-party applications in your tenant.

When both exist for the same API, per-application permissions take precedence over default permissions for third-party applications.

Per-application permissions

Auth0 Dashboard

To configure per-application permissions using the Auth0 Dashboard:

1. Navigate to Dashboard > Applications > APIs and select the API you want to configure application access for.
2. Go to the Settings tab and scroll down to Application Access Policy.
   • Configure User-Delegated Access to No apps allowed, Per-app authorization, or All apps allowed.
     • No apps allowed: No application can get an access token to the API.
     • Per-app authorization: Only applications with a client grant defined can get an access token for the API.
     • All apps allowed: Any application in your tenant can get an access token to the API.
   • Configure the Client Access to Per-app authorization or All apps allowed.
     • Per-app authorization: Only applications with a client grant defined can get an access token for the API.
     • All apps allowed: Any application in your tenant can get an access token to the API.
3. Select Save to save the Application Access Policy settings.

For per-application permissions, you need to individually authorize API access for each application.

1. Navigate to Applications > APIs and select the API.
2. Go to the Application Access tab.
3. Scroll to the application, select Edit, and then Grant Access for User-Delegated Access and/or Client Access. Then, select your desired permissions.
4. Select Save.

Management API

Make a POST request to the /client-grants endpoint with the following request body:

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

Default permissions for third-party applications

Third-party applications always require an explicit client grant to access any API, even when the API’s access policy is set to Allow All. To simplify management when you have many third-party applications or use Dynamic Client Registration, configure default grants or permissions that apply to all third-party applications automatically.

A default third-party client grant uses the default_for attribute instead of a client_id. You can also define per-application permissions by creating a client grant with a specific client_id. When both exist for the same API, per-application permissions take precedence.

System APIs (the Management API, My Account API, and others) do not support default third-party client grants. Third-party applications cannot be granted access to system APIs.

The default_for and client_id attributes are mutually exclusive. Each client grant must specify exactly one of them.

To learn how to configure API access policies for third-party applications, read Configure Third-Party Applications.

Auth0 Dashboard

To configure default permissions for third-party applications using the Auth0 Dashboard:

1. Navigate to Dashboard > Applications > APIs and select the API you want to configure application access for.
2. Go to the Settings tab and scroll down to Default Permissions for Third-Party Applications.
   • Configure User-Delegated Access and/or Client Access to Unauthorized, Authorized, or All.
     • Unauthorized: No permissions allowed.
     • Authorized: Pick and choose permissions.
     • All: Includes existing and future permissions.
3. Select Save.

Management API

Make a POST request to the /api/v2/client-grants endpoint with the following request body:

cURL

curl --request POST \
    --url 'https://YOUR_DOMAIN/api/v2/client-grants' \
    --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
        "default_for": "third_party_clients",
        "audience": "https://api.example.com",
        "scope": ["read:items", "write:items"],
        "subject_type": "user"
}'

Parameter	Type	Description
default_for	String	Specifies if this grant is automatically applied to certain app types. Set to third_party_clients to ensure all third-party apps have access to this API by default.
audience	String	The unique identifier (URI) of the API the grant is being created for.
scope	Array	A list of permissions (scopes) that are allowed as part of this grant.
subject_type	String	Defines the type of application access allowed for the API: user: Used for user-delegated access, which corresponds to flows that generate a token associated with an end-user. client: Used for machine-to-machine access, such as the Client Credentials Flow.

Update client grant

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

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

Delete client grant

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

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

Retrieve client grants

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

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'

Learn more

• API Access Policies for Applications
• Application Grant Types
• Third-Party Applications
• Configure Third-Party Applications