# Authorization Details

The BankID OIDC Provider supports the `authorization_details` parameter as defined in the [OAuth 2.0 Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/html/rfc9396) specification. This parameter allows including [permission statements](https://docs.stoe.no/bankid-with-biometrics/permission-types.md#available-permission-types) directly in [PAR](https://docs.stoe.no/bankid-oidc-provider/api/par.md) requests, eliminating the need for a separate [Permissions API](https://docs.stoe.no/bankid-with-biometrics/apis/permissions-api.md) request.

> **Note**
>
> The `authorization_details` parameter is only accepted in [PAR](https://docs.stoe.no/bankid-oidc-provider/api/par.md) requests.

## Request Format

The value is a URL-encoded JSON array containing a single permission item.

```json
[{
    "type": "payment.v1",
    "permission": "<base64url-encoded permission statement>"
}]
```

### Fields

| Field        | Type   | Required | Description                                                                                                                                                                                                        |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`       | string | Yes      | The permission type. See the [Permissions API](https://docs.stoe.no/bankid-with-biometrics/permission-types.md) for supported types.                                                                               |
| `permission` | string | Yes      | Base64url-encoded permission statement (e.g. payment details, text to approve). See [permission statement](https://docs.stoe.no/bankid-with-biometrics/flows/code-flow-for-payments.md#5-register-the-permission). |

All optional fields from the [Permissions API](https://docs.stoe.no/bankid-with-biometrics/apis/permissions-api.md) are also supported. Refer to the [Permissions API definition](https://docs.stoe.no/bankid-with-biometrics/apis/permissions-api.md) for the complete list of available fields.

## Token Response

When `authorization_details` is included in the request, the [token response](https://docs.stoe.no/bankid-oidc-provider/api/token.md) will include `authorization_details` as a top-level field, and the resulting tokens will contain additional claims:

### Token Response Body

The token response includes `authorization_details` as a top-level field alongside `access_token`, `id_token`, etc.

```json
{
  ...
  "authorization_details": [{
    "type": "payment.v1",
    "permission": "eyJub25jZSI6Imk...",
    "permission_digest": "x4Fz5C9hQq0m3LXKBA72WL8jKRXsQ6TnGiven3Gcz0k="
  }]
}
```

### ID Token

The ID token will include a `permission_digest` claim, a SHA-256 hash of the permission statement. This can be used to verify the integrity of the permission statement.

```json
{
  ...
  "permission_digest": "x4Fz5C9hQq0m3LXKBA72WL8jKRXsQ6TnGiven3Gcz0k="
}
```

### Access Token

The access token will include the `authorization_details` claim with the original request fields plus the `permission_digest`.

```json
{
  ...
  "authorization_details": [{
    "type": "payment.v1",
    "permission": "eyJub25jZSI6Imk...",
    "permission_digest": "x4Fz5C9hQq0m3LXKBA72WL8jKRXsQ6TnGiven3Gcz0k="
  }]
}
```

## Example

```http
POST [pushed_authorization_request_endpoint]
Content-Type: application/x-www-form-urlencoded

client_id=myclient-bankid-current
&scope=openid+profile
&redirect_uri=https%3A%2F%2Fmywebapp.example.org%2Fcallback
&response_type=code
&state=01e3ac8e-4a26-4dfb-79ca-2631394c4144
&nonce=1fb72f68-1bea-2ba2-12d7-24df1c999d1b
&code_challenge=rMU4NcLC3_O_tsTZ3gQE1ONoXD6OMZph_2zRuobajhQ
&code_challenge_method=S256
&authorization_details=%5B%7B%22type%22%3A%20%22payment.v1%22%2C%20%22permission%22%3A%22eyJub25jZSI6ImRXNXBjWFZsSUhaaGJIVmwiLCJpZCI6IlltRnphMlYwSUdsayIsInBheW1lbnRzIjpbeyJwYXltZW50SWQiOiJjR0Y1YldWdWRDQnBaQSIsImFtb3VudCI6IjEyMy40NSIsImN1cnJlbmN5IjoiTk9LIiwiY3JlZGl0b3JOYW1lIjoiU2Nyb29nZSBNY0R1Y2sifV19%22%7D%5D
```

## Error Responses

| HTTP Status | Error Code            | Description                                                                                    |
| ----------- | --------------------- | ---------------------------------------------------------------------------------------------- |
| 400         | `invalid_request`     | Invalid JSON structure, multi-item array, or invalid Base64url encoding in `permission` field. |
| 403         | `unauthorized_client` | Client does not have the required scopes for the requested permission type.                    |

## Size Limits

> **10,000 character limit**
>
> The `authorization_details` parameter is subject to a **10,000 character** limit. Requests exceeding this limit will be **silently dropped**: the authorization flow will proceed, but the `authorization_details` claim will not appear in the resulting tokens. If your permission statements require more than 10,000 characters, use the [Permissions API](https://docs.stoe.no/bankid-with-biometrics/apis/permissions-api.md) instead.

> **Large authorization_details leads to large access tokens**
>
> The `authorization_details` value (including the full base64url-encoded permission statement) is embedded in the access token as a claim. This means the access token size grows proportionally with the permission payload.
>
> Large access tokens are typically sent in the HTTP `Authorization` header. Many infrastructure components (reverse proxies, load balancers, application servers, CDNs) enforce default header size limits, commonly **8 KB**. An access token exceeding these limits will cause downstream API calls to fail with `HTTP 400`, `HTTP 502`, or connection-level errors depending on the component enforcing the limit.