> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-docs-event-stream-action-templates.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Learn how to configure Rich Authorization Requests (RAR) for a resource server.

# Configure Rich Authorization Requests (RAR)

Using [Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rar), clients can request and obtain <Tooltip tip="Fine-grained Authorization (FGA): Auth0 product allowing individual users access to specific objects or resources." cta="View Glossary" href="/docs/glossary?term=fine-grained+authorization">fine-grained authorization</Tooltip> data from <Tooltip tip="Resource Owner: Entity (such as a user or application) capable of granting access to a protected resource." cta="View Glossary" href="/docs/glossary?term=resource+owners">resource owners</Tooltip>, such as end users, during the [Authorization Code Flow with Pushed Authorization Requests (PAR)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-par) and [Client-Initiated Backchannel Authentication Flow](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow).

Rich Authorization Requests use the `authorization_details` parameter. This parameter accepts a JSON array of objects which may include detailed information about the authorization being requested, such as the specific resources or actions the client wants to access on behalf of the user.

You can render the requested `authorization_details` to the user using either:

* The browser, by using a [customized consent prompt](#set-customized-consent-prompt)
* A mobile application when using push notifications with the [Auth0 Guardian SDK or Auth0 Guardian app](/docs/secure/multi-factor-authentication/auth0-guardian)

To configure Rich Authorization Requests for a <Tooltip tip="Resource Server: Server hosting protected resources. Resource servers accept and respond to protected resource requests." cta="View Glossary" href="/docs/glossary?term=resource+server">resource server</Tooltip>, you must:

1. [Register `authorization_details` types](#register-authorization_details-types) for the resource server.
2. [Configure the API Access policies](#configure-the-api-access-policies) to allow your app to request those types.
3. [Set the customized consent prompt](#set-customized-consent-prompt) to render the `authorization_details`.
4. [Optional: Configure the consent policy for the resource server](#optional-configure-consent-policy-for-the-resource-server).

## Register `authorization_details` types

Each object in the JSON array must have a `type` field, which describes the shape of the object. An `authorization_details` array may contain multiple entries of the same `type`.

### Auth0 Guardian app

If you’re using the Auth0 Guardian app, then the `authorization_details` parameter value must have only one object in the array, and that object must conform to the following Auth0 schema:

| Field         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Example                                                                                                                           |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `type`        | Specifies the type of authorization request:<br /><ul><li>`urn:auth0:schemas:authorization-details`: The Auth0 URN indicates that the request will use the Auth0 schema.</li><li>`v1`: The schema version.</li><li>`user-profile`: Customer-provided value indicating that the request is for user profile information.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `urn:auth0:schemas:authorization-details:v1:user-profile`                                                                         |
| `instruction` | A human-readable message to the user approving the request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `Please approve the request.`                                                                                                     |
| `properties`  | A JSON object containing the specific user attributes or claims being requested. Each key (e.g., `email`, `full_name`) represents a particular user profile field:<br /><ul><li>`display`: A boolean value that determines whether the property should be shown to the user in the consent dialog. If `true`, it will be displayed; if `false`, it's an internal-only property not meant for user view.</li><li>`name`: The human-readable name for the property (e.g., "Email Address").</li><li>`display_order`: An integer that dictates the order in which properties will be shown in the consent dialog.</li><li>`description`: An optional, short explanation of the property's purpose.</li><li>`value`: The actual data value for the property (e.g., "[user@example.com](mailto:user@example.com)", "John Doe"). The data type can vary (string, integer, boolean, etc.).</li></ul> | `"properties": { "stringPropertyForDisplay": { "display": true, "name": "A String:", "display_order": "1", "value": "Value 1"} }` |

The following is an example `authorization_details` type with the Auth0 schema:

```json lines theme={null}
{
    "type": "urn:auth0:schemas:authorization-details:v1:user-profile",
    "instruction": "An instruction to the user",
    "properties": {
        "stringPropertyForDisplay": {
            "display": true,
            "name": "A String:",
            "display_order": 1,
            "value": "Value 1"
        },
        "numericPropertyForDisplay": {
            "display": true,
            "name": "A Number:",
            "display_order": 2,
            "description": "An optional description",
            "value": 100.00
        },
        "booleanPropertyForDisplay": {
            "display": true,
            "name": "A Boolean:",
            "display_order": 3,
            "value": true
        },
        "hiddenProperty": {
            "display": false,
            "value": "This value should not be displayed"
        }
    }
}
```

### Other notification channels

The `authorization_details` type does not need to use the Auth0 schema if you aren't using the Auth0 Guardian app. If you are displaying the `authorization_details` using a customized consent prompt or your own custom mobile app with the Auth0 Guardian SDK, then the following requirements apply:

* Maximum 5Kb
* Must be valid JSON
* Must be an array of objects
* Maximum of 5 entries in the array
* Every object must have a `type` property (that is pre-registered on the API)
* Maximum of 10 properties per object
* Maximum character length of property names is 255
* Maximum character length of property value is 255
* Maximum of 5 levels of nested objects
* Property names can only contain the following characters: `a-zA-Z0-9_.-`

The following is an example `authorization_details` of type `money_transfer` that does not use the Auth0 schema. It contains the following object fields:

* `instructedAmount`: The amount of money in USD to be transferred.
* `sourceAccount`: The source bank account from which the money will be transferred.
* `destinationAccount`: The destination bank account to which the money will be transferred.
* `beneficiary`: The recipient of the money transfer.
* `subject`: The subject line of the money transfer.

```json lines theme={null}
{
  "type": "money_transfer", 
  "instructedAmount": {"amount": 2500, "currency": "USD"},   
  "sourceAccount": "xxxxxxxxxxx1234", 
  "destinationAccount": "xxxxxxxxxxx9876", 
  "beneficiary": "Hanna Herwitz", 
  "subject": "A Lannister Always Pays His Debts"
}
```

You must register `authorization_details` types for a resource server, which is similar to registering allowed scopes. You can register `authorization_details` types with the [Auth0 Dashboard](https://manage.auth0.com/) or [Management API](https://auth0.com/docs/api/management/v2).

<Tabs>
  <Tab title="Auth0 Dashboard">
    To add `authorization_details` in the Auth0 Dashboard:

    1. Navigate to [Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/#/apis).
    2. Select the **Permissions** tab.
    3. Under **Add an Authorization Details type**, you can add multiple `authorization_details` types for your resource server. Enter an `authorization_details` type
    4. Select the **+Add** option.

    You can see the `authorization_details` types for your resource server under **List of Authorization Details Types**:

    <Frame>
      <img src="https://mintcdn.com/docs-dev-docs-event-stream-action-templates/wYcZudKzAy7DVE3d/docs/images/cdy7uua7fh8z/6qRpmbZiqaU8pSFDuWzUAy/951c827a307791de8df9cecd8f817351/Screenshot_2025-04-07_at_3.45.36_PM.png?fit=max&auto=format&n=wYcZudKzAy7DVE3d&q=85&s=33b292e055d81c76a5e58451e598dbf9" alt="" width="2058" height="536" data-path="docs/images/cdy7uua7fh8z/6qRpmbZiqaU8pSFDuWzUAy/951c827a307791de8df9cecd8f817351/Screenshot_2025-04-07_at_3.45.36_PM.png" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    To register  `authorization_details` types with an existing resource server, make a `PATCH` request to the [Update a resource server](https://auth0.com/docs/api/management/v2/resource-servers/patch-resource-servers-by-id) endpoint.

    The following code sample adds the `payment_initiation` and `money_transfer` types under `authorization_details` for a resource server:

    ```bash lines theme={null}
    curl --location --request PATCH 'https://$tenant/api/v2/resource-servers/$resource-server-id' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{
      "authorization_details": [{"type": "payment_initiation"}, {"type": "money_transfer"}]
      }'
    ```

    To create a new resource server with a registered `authorization_details` type, make a `POST` request to the `/resource-servers` endpoint.

    The following `POST` request creates a new resource server with `authorization_details` type `payment_initiation`:

    ```bash lines theme={null}
    curl --location --request POST 'https://$tenant/api/v2/resource-servers' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{
      "name": "Payments API",
      "identifier": "https://payments.api/",
      "authorization_details": [{"type": "payment_initiation"}]
      }'
    ```
  </Tab>
</Tabs>

## Configure the API Access policies

[API Access Policies for Applications](/docs/get-started/apis/api-access-policies-for-applications) control what applications can access your APIs and what scopes or `authorization_details` types they are allowed to access.

You can check your API's current policy using the Management API. Make a `GET` request to the [Get a resource server](https://auth0.com/docs/api/management/v2/resource-servers/get-resource-servers-by-id) endpoint and check the `subject_type_authorization` property in the response:

```bash lines theme={null}
curl --location --request GET 'https://$tenant/api/v2/resource-servers/$resource-server-id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json'
```

The `subject_type_authorization` property has values for `client.policy` and `user.policy`:

* If the policy value is `allow_all`, then applications or users can request all `authorization_details` types registered for the API.
* If the policy value is `require_client_grant`, then each type of `authorization_details` must be explicitly allowed by the client grant for that application.
* If the policy value is `deny_all`, then no application or user can request any of the `authorization_details` types registered for the API.

To learn more on how to manage client grants for applications, read [Application Access to APIs: Client Grants](/docs/get-started/applications/application-access-to-apis-client-grants) .

## Set customized consent prompt

You can render the `authorization_details` of a Rich Authorization Request in the consent prompt. To do so, configure the `customized-consent` prompt with the appropriate template partials.

You can set the customized consent prompt using the Auth0 CLI or Management API.

### Auth0 CLI

To configure the customized consent partials, run the `auth0 ul customize` command with the appropriate flags in your terminal:

```bash lines theme={null}
auth0 ul customize
```

To learn more, read the [auth0 universal-login customize documentation](https://auth0.github.io/auth0-cli/auth0_universal-login_customize.html).

### Management API

To configure the customized consent partials, make a `PUT` request to the `/prompts/customized-consent/partials` endpoint:

```bash lines theme={null}
curl --location --request PUT "https://$tenant/api/v2/prompts/customized-consent/partials" \
  --header "Authorization: Bearer $management_access_token" \
  --header "Content-Type: application/json" \
  --data '{
    "customized-consent": {
      "form-content": "<div style=\"font-size: 1.3em; font-weight: bold;\">Operation Details</div><hr style=\"margin: 10px 0;\"><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Transaction Type</div><div>{{ transaction.params.authorization_details[0].type }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Amount</div><div>{{ transaction.params.authorization_details[0].instructedAmount.amount }} {{ transaction.params.authorization_details[0].instructedAmount.currency }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Recipient</div><div>{{ transaction.params.authorization_details[0].beneficiary }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Destination Account</div><div>{{ transaction.params.authorization_details[0].destinationAccount }}</div><div style=\"margin-bottom: 20px;\"></div>"
    }
  }'
```

The customized consent template renders the `authorization_details` in the following consent prompt that Auth0 shows to the end user:

<Frame>
  <img src="https://mintcdn.com/docs-dev-docs-event-stream-action-templates/RjB12i6aOVmBONJv/docs/images/cdy7uua7fh8z/9NdSMIBWrNI2kbPuaVpon/afc3dde316d5a3577d0d181e6046fa81/Screenshot_2025-03-31_at_3.24.40_PM.png?fit=max&auto=format&n=RjB12i6aOVmBONJv&q=85&s=25e8e3d90d28ddecd3891d68c844f1ba" alt="" width="1236" height="714" data-path="docs/images/cdy7uua7fh8z/9NdSMIBWrNI2kbPuaVpon/afc3dde316d5a3577d0d181e6046fa81/Screenshot_2025-03-31_at_3.24.40_PM.png" />
</Frame>

In the [email notifications with CIBA and RAR flow](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/email-notifications-with-ciba), you need to customize the consent prompt to show the approval or rejection screens to the user:

<Frame>
  <img src="https://mintcdn.com/docs-dev-docs-event-stream-action-templates/6a0bOHQ-5WYDVwHQ/docs/images/ciba/user_accepts_the_authentication_request.png?fit=max&auto=format&n=6a0bOHQ-5WYDVwHQ&q=85&s=3f7f6d9a9e1a0071f23a12b6edaac8dc" alt="User accepts the authentication request" style={{ width: '300px', height: 'auto' }} width="730" height="982" data-path="docs/images/ciba/user_accepts_the_authentication_request.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/docs-dev-docs-event-stream-action-templates/6a0bOHQ-5WYDVwHQ/docs/images/ciba/user_rejects_authentication_request.png?fit=max&auto=format&n=6a0bOHQ-5WYDVwHQ&q=85&s=343e50bebf1e8d611d2b0e45408d926e" alt="User accepts the authentication request" style={{ width: '300px', height: 'auto' }} width="774" height="1038" data-path="docs/images/ciba/user_rejects_authentication_request.png" />
</Frame>

To learn more about how to customize the consent prompt, read:

* [Customize Universal Login Pages](/docs/customize/login-pages/universal-login/customize-templates)
* [Customize Universal Login with the No-Code Editor](/docs/customize/login-pages/universal-login/customize-themes)
* [Set partials for a prompt API documentation](/docs/api/management/v2/prompts/put-partials)

## Optional: Configure consent policy for the resource server

The resource server's consent policy determines whether Auth0 stores the `authorization_details` values and makes them available to mobile applications when a push notification is sent.

Review Auth0's standard consent policy behavior for a request containing `authorization_details`:

| Flow                                             | Push notification sent | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Any                                              | No                     | The customized consent prompt is shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Authorization Code Flow with PAR                 | Yes                    | No consent prompt is shown. The consent must be shown on the mobile application that receives the push notification challenge.<br />If the Auth0 Guardian app is used, it will automatically display the `authorization_details` to the user.<br />If a custom mobile app is used, the `authorization_details` can be retreived using the Auth0 Guardian SDK.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Client-Initiated Backchannel Authentication Flow | Yes                    | If the Auth0 Guardian App is being used to authorize the CIBA request, the `authorization_details` will be fetched automatically and displayed.<br />If a custom mobile app is used to authorize the CIBA request, the `authorization_details` can be retreived using the Auth0 Guardian SDK.<br />If the CIBA request is being authorized using a web link (e.g. from an email), then the customized consent prompt will be shown.<br />Customers may choose to trigger a push notification as a second factor for the CIBA request when the user is approving it by a web link, in which case the behavior is the same as above. The Auth0 Guardian app automatically displays the `authorization_details` to the user again, while custom mobile apps can choose to retrieve the `authorization_details` using the Auth0 Guardian SDK. |

Customers can also set the `consent_policy` to `transactional-authorization-with-mfa`, which has the following behavior:

| Flow                                             | Push notification sent | Behaviour                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Authorization Code Flow with PAR                 | No                     | The customized consent prompt is shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Authorization Code Flow with PAR                 | Yes                    | No consent prompt is shown. The customer solution must show the consent using their own user interface. Auth0 will allocate a unique ID for the request and expose it to the Post-Login Action as `event.transaction.linking_id` along with the `event.transaction.requested_authorization_details`.<br />If the Auth0 Guardian App is used, the `authorization_details` will NOT be displayed.<br />If a custom mobile app is used, the push notification will include the `linking_id`, allowing application builders to retrieve the `authorization_details` from their own APIs if required. |
| Client-Initiated Backchannel Authentication Flow | Any                    | CIBA flow is not supported with `transactional-authorization-with-mfa` consent policy                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

You can set the consent policy for a resource server with the [Auth0 Dashboard](https://manage.auth0.com/) or [Management API](https://auth0.com/docs/api/management/v2).

<Tabs>
  <Tab title="Auth0 Dashboard">
    Set the consent policy in your API settings using the Auth0 Dashboard.

    1. Navigate to [Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/#/apis).
    2. Select the **Settings** tab.
    3. Under **Access Settings**, choose the **Standard** consent policy.
    4. Save your changes.

    <Frame>
      <img src="https://mintcdn.com/docs-dev-docs-event-stream-action-templates/RDh-UBFSkTEu_d9f/docs/images/cdy7uua7fh8z/3gr8Sf98gh8CUkjnlodNk/cf33985b1e5b62082d46e4f5c8bbed6f/Screenshot_2025-03-31_at_8.22.45_PM.png?fit=max&auto=format&n=RDh-UBFSkTEu_d9f&q=85&s=73b82c27c5208b1a518c50a4c8094751" alt="Dashboard > Applications > APIs > Settings > Access Settings" data-og-width="1976" width="1976" data-og-height="1046" height="1046" data-path="docs/images/cdy7uua7fh8z/3gr8Sf98gh8CUkjnlodNk/cf33985b1e5b62082d46e4f5c8bbed6f/Screenshot_2025-03-31_at_8.22.45_PM.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/docs-dev-docs-event-stream-action-templates/RDh-UBFSkTEu_d9f/docs/images/cdy7uua7fh8z/3gr8Sf98gh8CUkjnlodNk/cf33985b1e5b62082d46e4f5c8bbed6f/Screenshot_2025-03-31_at_8.22.45_PM.png?w=280&fit=max&auto=format&n=RDh-UBFSkTEu_d9f&q=85&s=7f296649c185adc80a4c1879d6e91a92 280w, https://mintcdn.com/docs-dev-docs-event-stream-action-templates/RDh-UBFSkTEu_d9f/docs/images/cdy7uua7fh8z/3gr8Sf98gh8CUkjnlodNk/cf33985b1e5b62082d46e4f5c8bbed6f/Screenshot_2025-03-31_at_8.22.45_PM.png?w=560&fit=max&auto=format&n=RDh-UBFSkTEu_d9f&q=85&s=703d59252360aeaa7a8fd852cab763c3 560w, https://mintcdn.com/docs-dev-docs-event-stream-action-templates/RDh-UBFSkTEu_d9f/docs/images/cdy7uua7fh8z/3gr8Sf98gh8CUkjnlodNk/cf33985b1e5b62082d46e4f5c8bbed6f/Screenshot_2025-03-31_at_8.22.45_PM.png?w=840&fit=max&auto=format&n=RDh-UBFSkTEu_d9f&q=85&s=3b262918ebb2560a8a1ed899fd703237 840w, https://mintcdn.com/docs-dev-docs-event-stream-action-templates/RDh-UBFSkTEu_d9f/docs/images/cdy7uua7fh8z/3gr8Sf98gh8CUkjnlodNk/cf33985b1e5b62082d46e4f5c8bbed6f/Screenshot_2025-03-31_at_8.22.45_PM.png?w=1100&fit=max&auto=format&n=RDh-UBFSkTEu_d9f&q=85&s=a9b8b6b43865593f66b7ab0d1d6dfa05 1100w, https://mintcdn.com/docs-dev-docs-event-stream-action-templates/RDh-UBFSkTEu_d9f/docs/images/cdy7uua7fh8z/3gr8Sf98gh8CUkjnlodNk/cf33985b1e5b62082d46e4f5c8bbed6f/Screenshot_2025-03-31_at_8.22.45_PM.png?w=1650&fit=max&auto=format&n=RDh-UBFSkTEu_d9f&q=85&s=8c3b33e04524e4a87698781713e12d27 1650w, https://mintcdn.com/docs-dev-docs-event-stream-action-templates/RDh-UBFSkTEu_d9f/docs/images/cdy7uua7fh8z/3gr8Sf98gh8CUkjnlodNk/cf33985b1e5b62082d46e4f5c8bbed6f/Screenshot_2025-03-31_at_8.22.45_PM.png?w=2500&fit=max&auto=format&n=RDh-UBFSkTEu_d9f&q=85&s=1ec2ee4778e4f0e8afc8598157e5582e 2500w" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    To set the consent policy for a resource server or API using the Management API, send a `PATCH` request to the [Update a resource server](https://auth0.com/docs/api/management/v2/resource-servers/patch-resource-servers-by-id) endpoint. In the `PATCH` request, set the `consent_policy` to `standard`:

    ```bash wrap lines theme={null}
    curl --location --request PATCH 'https://$tenant/api/v2/resource-servers/$resource-server-id' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{ "consent_policy": "standard" }'
    ```
  </Tab>
</Tabs>