IdP API Reference

Authorization — IdP API

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

Base URL: https://idp.authpi.com — see the IdP API overview for the supported flows, or try these endpoints in the interactive reference.

`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

Your application redirects the user to this endpoint with required parameters
The user authenticates with their chosen method (password, social login, passkeys, etc.)
Upon success, AuthPI redirects to your redirect_uri with a code parameter
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, RFC 7636 PKCE

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`