Configure Rich Authorization Requests (RAR)

Using Rich Authorization Requests (RAR), clients can request and obtain data from , such as end users, during the Authorization Code Flow with Pushed Authorization Requests (PAR) and 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
A mobile application when using push notifications with the Auth0 Guardian SDK or Auth0 Guardian app

To configure Rich Authorization Requests for a , you must:

Register authorization_details types for the resource server.
Configure the API Access policies to allow your app to request those types.
Set the customized consent prompt to render the authorization_details.
Optional: Configure the 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: `urn:auth0:schemas:authorization-details`: The Auth0 URN indicates that the request will use the Auth0 schema. `v1`: The schema version. `user-profile`: Customer-provided value indicating that the request is for user profile information.	`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: `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. `name`: The human-readable name for the property (e.g., “Email Address”). `display_order`: An integer that dictates the order in which properties will be shown in the consent dialog. `description`: An optional, short explanation of the property’s purpose. `value`: The actual data value for the property (e.g., “user@example.com”, “John Doe”). The data type can vary (string, integer, boolean, etc.).	`"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:

{
    "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.

{
  "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 or Management API.

Auth0 Dashboard
Management API

To add authorization_details in the Auth0 Dashboard:

Navigate to Auth0 Dashboard > Applications > APIs.
Select the Permissions tab.
Under Add an Authorization Details type, you can add multiple authorization_details types for your resource server. Enter an authorization_details type
Select the +Add option.

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

To register authorization_details types with an existing resource server, make a PATCH request to the Update a resource server endpoint.The following code sample adds the payment_initiation and money_transfer types under authorization_details for a resource server:

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:

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

Configure the API Access policies

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 endpoint and check the subject_type_authorization property in the response:

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

auth0 ul customize

To learn more, read the auth0 universal-login customize documentation.

Management API

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

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:

In the email notifications with CIBA and RAR flow, you need to customize the consent prompt to show the approval or rejection screens to the user:

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

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. If the Auth0 Guardian app is used, it will automatically display the `authorization_details` to the user. 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. If a custom mobile app is used to authorize the CIBA request, the `authorization_details` can be retreived using the Auth0 Guardian SDK. If the CIBA request is being authorized using a web link (e.g. from an email), then the customized consent prompt will be shown. 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`. If the Auth0 Guardian App is used, the `authorization_details` will NOT be displayed. 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 or Management API.

Auth0 Dashboard
Management API

Set the consent policy in your API settings using the Auth0 Dashboard.

Navigate to Auth0 Dashboard > Applications > APIs.
Select the Settings tab.
Under Access Settings, choose the Standard consent policy.
Save your changes.

Dashboard > Applications > APIs > Settings > Access Settings

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 endpoint. In the PATCH request, set the consent_policy to standard:

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

Auth0 Onboarding

Quickstarts

Learn the Basics

Configure Auth0

Plan and Design

Configure Rich Authorization Requests (RAR)

Register `authorization_details` types

Auth0 Guardian app

Other notification channels

Configure the API Access policies

Auth0 CLI

Management API

​Register authorization_details types

​Auth0 Guardian app

​Other notification channels

​Configure the API Access policies

​Set customized consent prompt

​Auth0 CLI

​Management API

​Optional: Configure consent policy for the resource server

Register `authorization_details` types

Auth0 Guardian app

Other notification channels

Configure the API Access policies

Set customized consent prompt

Auth0 CLI

Management API

Optional: Configure consent policy for the resource server