> Markdown version of https://authpi.com/docs/reference/idp-api/authorization/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Authorization — AuthPI Identity Provider API

Authorization endpoints for initiating OAuth 2.0 and OpenID Connect flows. Use these endpoints to request user authentication and obtain authorization codes.

## GET /{issuer_id}/authorize

**Authorization Endpoint**

Initiates the OAuth 2.0 Authorization Code flow (RFC 6749 Section 4.1).

This endpoint is the starting point for user authentication. Redirect users here to begin the authorization process. After successful authentication, users are redirected back to your `redirect_uri` with an authorization code.

## Flow Overview

1. Your application redirects the user to this endpoint with required parameters
2. The user authenticates with their chosen method (password, social login, passkeys, etc.)
3. Upon success, AuthPI redirects to your `redirect_uri` with a `code` parameter
4. Exchange the code for tokens at the `/token` endpoint

## PKCE Requirement

**PKCE (RFC 7636) is required for public clients** (SPAs, mobile apps) and strongly recommended for all clients. Only the `S256` challenge method is supported—the `plain` method is not allowed for security reasons.

## Session State

If the authorization succeeds, a `session_state` parameter is included in the redirect for OpenID Connect Session Management.

## Error Handling

Errors are returned either:
- As a redirect to your `redirect_uri` with `error` and `error_description` parameters
- As an HTTP error response if the `redirect_uri` is invalid or missing

**Specifications**: [RFC 6749 Section 4.1](https://tools.ietf.org/html/rfc6749#section-4.1), [RFC 7636 PKCE](https://tools.ietf.org/html/rfc7636)

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | string | Optional | Your application's client ID |
| `redirect_uri` | string | Optional | URI to redirect after authorization |
| `response_type` | string | Optional | Must be 'code' for Authorization Code flow |
| `scope` | string | Optional | Space-separated list of scopes |
| `state` | string | Optional | Opaque value for CSRF protection |
| `nonce` | string | Optional | String value for ID token replay attack mitigation |
| `code_challenge` | string | Optional | PKCE code challenge (S256) |
| `code_challenge_method` | string | Optional | PKCE challenge method (must be S256) |
| `prompt` | string | Optional | Space-separated list: none, login, consent, select_account |
| `max_age` | string | Optional | Maximum authentication age in seconds |
| `acr_values` | string | Optional | Requested Authentication Context Class References |
| `login_hint` | string | Optional | Hint about the user's identifier |
| `audience` | string | Optional | Requested audience for access token (RFC 8707) |
| `org` | string | Optional | Selected organization ID for org-restricted tokens |
| `response_mode` | string | Optional | Response mode: query or fragment |
| `flow` | string | Optional | Flow ID to resume an existing authorization flow |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 302 | **Redirect** - User redirected to client or login page. | — |
| 400 | **Bad Request** - The request is malformed or missing required parameters. | `OAuthError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `OAuthError` |
| 403 | **Forbidden** - The authenticated client or user lacks permission for this operation. | `OAuthError` |
| 404 | **Not Found** - The requested resource does not exist. | `OAuthError` |
| 422 | **Unprocessable Entity** - The request syntax is correct but the data cannot be processed. | `OAuthError` |
| 429 | **Too Many Requests** - Rate limit exceeded. | `OAuthError` |
| 500 | **Internal Server Error** - An unexpected error occurred. | `OAuthError` |

## POST /{issuer_id}/authorize

**Authorization Endpoint**

Initiates the OAuth 2.0 Authorization Code flow (RFC 6749 Section 4.1).

This endpoint is the starting point for user authentication. Redirect users here to begin the authorization process. After successful authentication, users are redirected back to your `redirect_uri` with an authorization code.

## Flow Overview

1. Your application redirects the user to this endpoint with required parameters
2. The user authenticates with their chosen method (password, social login, passkeys, etc.)
3. Upon success, AuthPI redirects to your `redirect_uri` with a `code` parameter
4. Exchange the code for tokens at the `/token` endpoint

## PKCE Requirement

**PKCE (RFC 7636) is required for public clients** (SPAs, mobile apps) and strongly recommended for all clients. Only the `S256` challenge method is supported—the `plain` method is not allowed for security reasons.

## Session State

If the authorization succeeds, a `session_state` parameter is included in the redirect for OpenID Connect Session Management.

## Error Handling

Errors are returned either:
- As a redirect to your `redirect_uri` with `error` and `error_description` parameters
- As an HTTP error response if the `redirect_uri` is invalid or missing

**Specifications**: [RFC 6749 Section 4.1](https://tools.ietf.org/html/rfc6749#section-4.1), [RFC 7636 PKCE](https://tools.ietf.org/html/rfc7636)

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | string | Optional | Your application's client ID |
| `redirect_uri` | string | Optional | URI to redirect after authorization |
| `response_type` | string | Optional | Must be 'code' for Authorization Code flow |
| `scope` | string | Optional | Space-separated list of scopes |
| `state` | string | Optional | Opaque value for CSRF protection |
| `nonce` | string | Optional | String value for ID token replay attack mitigation |
| `code_challenge` | string | Optional | PKCE code challenge (S256) |
| `code_challenge_method` | string | Optional | PKCE challenge method (must be S256) |
| `prompt` | string | Optional | Space-separated list: none, login, consent, select_account |
| `max_age` | string | Optional | Maximum authentication age in seconds |
| `acr_values` | string | Optional | Requested Authentication Context Class References |
| `login_hint` | string | Optional | Hint about the user's identifier |
| `audience` | string | Optional | Requested audience for access token (RFC 8707) |
| `org` | string | Optional | Selected organization ID for org-restricted tokens |
| `response_mode` | string | Optional | Response mode: query or fragment |
| `flow` | string | Optional | Flow ID to resume an existing authorization flow |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 302 | **Redirect** - User redirected to client or login page. | — |
| 400 | **Bad Request** - The request is malformed or missing required parameters. | `OAuthError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `OAuthError` |
| 403 | **Forbidden** - The authenticated client or user lacks permission for this operation. | `OAuthError` |
| 404 | **Not Found** - The requested resource does not exist. | `OAuthError` |
| 422 | **Unprocessable Entity** - The request syntax is correct but the data cannot be processed. | `OAuthError` |
| 429 | **Too Many Requests** - Rate limit exceeded. | `OAuthError` |
| 500 | **Internal Server Error** - An unexpected error occurred. | `OAuthError` |