# How to Configure authorizationDetails for Rich Authorization Requests in Auth0-Auth-JS

> Learn to configure authorizationDetails for Rich Authorization Requests in Auth0-Auth-JS. Easily pass authorization details via the SDK for secure, streamlined access.

- Repository: [Auth0/auth0-auth-js](https://github.com/auth0/auth0-auth-js)
- Tags: how-to-guide
- Published: 2026-02-25

---

**To configure authorizationDetails for Rich Authorization Requests (RAR) in Auth0-Auth-JS, pass an array of `AuthorizationDetails` objects via the `authorizationDetails` option when calling `backchannelAuthentication()` or `initiateBackchannelAuthentication()`. The SDK automatically serializes this array to JSON and transmits it as the `authorization_details` parameter to Auth0's `/bc-authorize` endpoint.**

Rich Authorization Requests (RAR), defined in RFC 8707, enable fine-grained authorization specifications in OAuth 2.0 flows. The `auth0/auth0-auth-js` repository implements first-class, type-safe support for RAR within Client-Initiated Backchannel Authentication (CIBA) flows, allowing developers to define precise authorization requirements using the `authorizationDetails` parameter.

## Understanding the AuthorizationDetails Interface

The SDK models RAR data using the `AuthorizationDetails` interface defined in [`src/types.ts`](https://github.com/auth0/auth0-auth-js/blob/main/src/types.ts) (lines 489-492). This interface requires a `type` field representing the RAR type identifier, while allowing arbitrary extension properties for custom authorization data.

```typescript
// src/types.ts
export interface AuthorizationDetails {
  readonly type: string;
  readonly [parameter: string]: unknown;
}

```

This structure accommodates standard RAR types (such as `payment_initiation` or `account_information`) alongside custom domain-specific types. The index signature permits any additional properties required by your specific authorization scenario.

## Configuring authorizationDetails in CIBA Methods

The library supports RAR configuration in both full token exchange and initiate-only CIBA methods. In [`src/auth-client.ts`](https://github.com/auth0/auth0-auth-js/blob/main/src/auth-client.ts), the SDK handles serialization via `JSON.stringify()` before appending the parameter to the request.

### Using backchannelAuthentication

When calling `backchannelAuthentication` (lines 480-482 in [`src/auth-client.ts`](https://github.com/auth0/auth0-auth-js/blob/main/src/auth-client.ts)), supply the `authorizationDetails` array in the options object:

```typescript
params.append('authorization_details', JSON.stringify(options.authorizationDetails));

```

This automatic serialization ensures proper URL-encoding and JSON formatting for the Auth0 `/bc-authorize` endpoint.

### Using initiateBackchannelAuthentication

For flows requiring only the `auth_req_id` (polling scenarios), `initiateBackchannelAuthentication` (lines 534-536 in [`src/auth-client.ts`](https://github.com/auth0/auth0-auth-js/blob/main/src/auth-client.ts)) implements identical RAR handling:

```typescript
params.append('authorization_details', JSON.stringify(options.authorizationDetails));

```

Both methods append the serialized data to the request body sent to Auth0's backchannel authorization endpoint.

### Alternative: Raw authorization_params Configuration

If you construct authorization parameters manually, embed the JSON string directly within the `authorizationParams` object:

```typescript
await authClient.backchannelAuthentication({
  bindingMessage: 'Approve login',
  loginHint: { sub: 'auth0|987654321' },
  authorizationParams: {
    authorization_details: JSON.stringify([
      { type: 'accepted' },
    ]),
  },
});

```

This approach bypasses the typed `authorizationDetails` option while achieving identical protocol behavior.

## Receiving Authorization Details in TokenResponse

After Auth0 processes the request, any echoed RAR data returns in the token response. The `TokenResponse` class (defined in [`src/types.ts`](https://github.com/auth0/auth0-auth-js/blob/main/src/types.ts), lines 525-531) exposes this via the optional `authorizationDetails` property:

```typescript
// TokenResponse includes:
authorizationDetails?: AuthorizationDetails[];

```

Unit tests in [`src/auth-client.spec.ts`](https://github.com/auth0/auth0-auth-js/blob/main/src/auth-client.spec.ts) (lines 925-933) verify that supplied `authorizationDetails` arrays correctly round-trip through the Auth0 backend and appear in the response object.

## Complete Code Examples for RAR Configuration

### Basic RAR with Immediate Token Exchange

Configure Rich Authorization Requests during a standard backchannel authentication flow:

```typescript
import { AuthClient } from '@auth0/auth0-auth-js';

const authClient = new AuthClient({
  domain: 'YOUR_DOMAIN',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  authorizationParams: { audience: 'https://api.example.com' },
});

const response = await authClient.backchannelAuthentication({
  bindingMessage: 'Approve login for ExampleApp',
  loginHint: { sub: 'auth0|1234567890' },
  authorizationDetails: [
    {
      type: 'urn:example:payment',
      actions: ['pay', 'refund'],
      amount: 49.99,
      currency: 'USD',
    },
  ],
});

console.log('Access token:', response.accessToken);
console.log('Returned RAR type:', response.authorizationDetails?.[0].type);

```

### RAR in Initiate-Only Flows

Configure authorizationDetails when obtaining only the authorization request ID for later polling:

```typescript
const init = await authClient.initiateBackchannelAuthentication({
  bindingMessage: 'Approve login',
  loginHint: { sub: 'auth0|123' },
  authorizationDetails: [{ type: 'accepted' }],
});

console.log('Auth request ID:', init.authReqId);
// authorization_details was sent to Auth0 during initiation

```

## Summary

- The `AuthorizationDetails` interface in [`src/types.ts`](https://github.com/auth0/auth0-auth-js/blob/main/src/types.ts) defines the RAR structure with a required `type` string and extensible property signatures.
- Both `backchannelAuthentication` and `initiateBackchannelAuthentication` methods in [`src/auth-client.ts`](https://github.com/auth0/auth0-auth-js/blob/main/src/auth-client.ts) accept an `authorizationDetails` option and automatically serialize it using `JSON.stringify()` before transmission.
- Auth0 validates the RAR payload against the client's configured `authorization_details_types_supported` and echoes applicable details in the `TokenResponse`, accessible via the `authorizationDetails` property.
- The unit tests in [`src/auth-client.spec.ts`](https://github.com/auth0/auth0-auth-js/blob/main/src/auth-client.spec.ts) confirm correct parameter forwarding and response handling for Rich Authorization Requests.

## Frequently Asked Questions

### What RFC standard defines Rich Authorization Requests?

Rich Authorization Requests are defined in RFC 8707. The Auth0-Auth-JS SDK implements this standard specifically for CIBA flows by mapping the JavaScript `authorizationDetails` option to the OAuth 2.0 `authorization_details` parameter.

### Can I use authorizationDetails with authorization code flows or other grant types?

Based on the current implementation in [`src/auth-client.ts`](https://github.com/auth0/auth0-auth-js/blob/main/src/auth-client.ts), the `authorizationDetails` parameter is specifically handled within the `backchannelAuthentication` and `initiateBackchannelAuthentication` methods for CIBA flows. Support for other OAuth 2.0 flows would require explicit implementation in the respective authorization methods.

### How does the SDK validate the authorizationDetails structure?

The SDK relies on TypeScript typing via the `AuthorizationDetails` interface but does not perform runtime validation of RAR content. Auth0's authorization server validates the `authorization_details` against the client configuration's `authorization_details_types_supported` after receiving the request.

### What happens if Auth0 modifies the authorizationDetails in the response?

The `TokenResponse` constructor captures any `authorization_details` returned by Auth0 into the `authorizationDetails` property (as defined in [`src/types.ts`](https://github.com/auth0/auth0-auth-js/blob/main/src/types.ts) lines 525-531). Always inspect `response.authorizationDetails` after token exchange, as Auth0 may filter or modify the requested authorization details based on policy or user consent.