> ## 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 use Rich Authorization Requests (RAR) with the Authorization Code Flow.

# Authorization Code Flow with 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.  Clients can pass RAR data to the Pushed Authorization Request (PAR) endpoint as part of the Authorization Code Flow. To learn more, read [Configure Pushed Authorization Requests](/docs/get-started/applications/configure-par).

In a traditional <Tooltip tip="OAuth 2.0: Authorization framework that defines authorization protocols and workflows." cta="View Glossary" href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> flow, when a client requests access to a <Tooltip tip="OAuth 2.0: Authorization framework that defines authorization protocols and workflows." cta="View Glossary" href="/docs/glossary?term=resource+server">resource server</Tooltip> using [scopes](/docs/get-started/apis/scopes), the resource owner grants the client access to those resources. In a Rich Authorization Request, clients can pass an `authorization_details` parameter to the `/par` endpoint to request more granular permissions than those requested in scopes. This allows for more fine-grained control over resource access for both clients and resource owners, mitigating security risks associated with over-provisioning access.

Because Auth0 only supports validating `authorization_details` types, you must implement validation for the JSON objects in `authorization_details`. To learn more, read [Configure Rich Authorization Requests](/docs/get-started/apis/configure-rich-authorization-requests).

## How it works

In a Rich Authorization Request, the `authorization_details` parameter is a JSON array of objects, each of which must include a `type` field represented as a string. The `type` field determines the customizable object fields. An `authorization_details` array may contain multiple entries of the same type. To learn more about how to register `authorization_details` types, read [Configure Rich Authorization Requests](/docs/get-started/apis/configure-rich-authorization-requests).

Auth0 presents the `authorization_details` to the user to authorize in a custom consent screen. To learn more, read [Set customized consent prompt](/docs/get-started/apis/configure-rich-authorization-requests#set-customized-consent-prompt).

You must pass the `authorization_details` parameter to the `/par` endpoint, which enables the Auth0 <Tooltip tip="Authorization Server: Centralized server that contributes to defining the boundaries of a user’s access. For example, your authorization server can control the data, tasks, and features available to a user." cta="View Glossary" href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip> to perform early validation of the `type`. The `/par` endpoint passes authorization requests on the back channel to avoid sensitive data leaking in the front channel, such as the browser. Once you’ve passed the authorization request to the `/par` endpoint, the application will redirect to the `/authorize` endpoint and then proceed with the Authorization Code Flow. To learn more, read [Authorization Code Flow with PAR](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-par).

To complete the Authorization Code Flow, exchange the authorization code at the `/oauth/token` endpoint, as in the following example:

```http lines theme={null}
POST https://{YOUR_DOMAIN}.auth0.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id={YOUR_CLIENT_ID}&client_secret={YOUR_CLIENT_SECRET}&code={AUTHORIZATION_CODE}&redirect_uri=https://jwt.io
```

When successful, you should receive a response with the <Tooltip tip="Access Token: Authorization credential, in the form of an opaque string or JWT, used to access an API." cta="View Glossary" href="/docs/glossary?term=access+token">access token</Tooltip> and `authorization_details` array:

```json lines theme={null}
{
  "access_token": "ey...ZQ",
  "expires_in": 86400,
  "authorization_details": [
{
  "type": "money_transfer", 
  "instructedAmount": {"amount": 2500, "currency": "USD"},   
  "sourceAccount": "xxxxxxxxxxx1234", 
  "destinationAccount": "xxxxxxxxxxx9876", 
  "beneficiary": "Hanna Herwitz", 
  "subject": "A Lannister Always Pays His Debts"
}
  ],
  "token_type": "Bearer"
}
```

As part of [JWT best practices](https://datatracker.ietf.org/doc/html/rfc9068#name-privacy-considerations), the client can use `authorization_details` to understand the scope of the authorization granted to it without having to inspect the access token. If the requested <Tooltip tip="Audience: Unique identifier of the audience for an issued token. Named aud in a token, its value contains the ID of either an application (Client ID) for an ID Token or an API (API Identifier) for an Access Token." cta="View Glossary" href="/docs/glossary?term=audience">audience</Tooltip> is an API that requires [JWE access tokens](/docs/secure/tokens/json-web-tokens), the `/oauth/token`endpoint returns a response that omits all object fields except for `type` from `authorization_details`. Access token claims are unaffected in the response.

```json lines theme={null}
{
  "iss": "https://my_tenant.auth0.com/",
  "sub": "auth0|me",
  "aud": "https://myapi.authzero.com",
  "iat": 1683661385,
  "exp": 1683747785,
  "azp": "my_client",
  "authorization_details": [
{
  "type": "money_transfer", 
  "instructedAmount": {"amount": 2500, "currency": "USD"},   
  "sourceAccount": "xxxxxxxxxxx1234", 
  "destinationAccount": "xxxxxxxxxxx9876", 
  "beneficiary": "Hanna Herwitz", 
  "subject": "A Lannister Always Pays His Debts"
}
  ]
}
```

## Configure RAR for the Authorization Code Flow

Before configuring Rich Authorization Requests for the Authorization Code Flow, you must:

* Create a [custom domain](/docs/customize/custom-domains).
* Create a [custom Universal Login Pages](/docs/customize/login-pages/universal-login/customize-templates) template. To learn how to customize a <Tooltip tip="Universal Login: Your application redirects to Universal Login, hosted on Auth0's Authorization Server, to verify a user's identity." cta="View Glossary" href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> Page template, read the [Page templates API](/docs/customize/login-pages/universal-login/customize-templates#page-templates-api) documentation.

To configure RAR for the Authorization Code Flow, you need to:

* Register `authorization_details` types for a resource server.
* Set the customized consent prompt.

To learn more, read [Configure Rich Authorization Requests](/docs/get-started/apis/configure-rich-authorization-requests).

## Access `authorization_details` in Actions

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Auth0 does not support updating RAR using Actions.
</Callout>

Auth0 exposes the `authorization_details` parameter in the [post-login Action](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object) via the `event.transaction.requested_authorization_details` property. You can reference this property in an Action to show transaction details to the user in an [MFA challenge](/docs/secure/highly-regulated-identity/transactional-authorization-with-authorization-code-flow#push-notifications).

## What doesn’t Auth0 support?

Auth0 doesn’t support:

* Updating RAR using Actions.
* Advertising RAR types for clients to discover.
* Validating RAR objects beyond checking that they have a type property that matches allowed types for the API. For more information, see [Configure RAR](/docs/get-started/apis/configure-rich-authorization-requests).

## Learn more

* [Configure Rich Authorization Requests (RAR)](/docs/get-started/apis/configure-rich-authorization-requests)