Skip to main content
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: To configure Rich Authorization Requests for a , you must:
  1. Register authorization_details types for the resource server.
  2. Configure the API Access policies to allow your app to request those types.
  3. Set the customized consent prompt to render the authorization_details.
  4. 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:
FieldDescriptionExample
typeSpecifies 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
instructionA human-readable message to the user approving the request.Please approve the request.
propertiesA 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.
To add authorization_details in the Auth0 Dashboard:
  1. Navigate to Auth0 Dashboard > Applications > 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:

​
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:
User accepts the authentication request
User accepts the authentication request
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:
FlowPush notification sentBehavior
AnyNoThe customized consent prompt is shown.
Authorization Code Flow with PARYes

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 FlowYes

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:
FlowPush notification sentBehaviour
Authorization Code Flow with PARNoThe customized consent prompt is shown.
Authorization Code Flow with PARYes

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 FlowAnyCIBA 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.
Set the consent policy in your API settings using the Auth0 Dashboard.
  1. Navigate to Auth0 Dashboard > Applications > APIs.
  2. Select the Settings tab.
  3. Under Access Settings, choose the Standard consent policy.
  4. Save your changes.
Dashboard > Applications > APIs > Settings > Access Settings