GET /api/oauth/authorize

Start the OAuth 2.0 authorization-code flow.

This is a browser-facing endpoint. It validates the request, redirects unauthenticated users into the portal login flow, shows the consent screen, and then redirects back with an authorization code.

Endpoint

GET /api/oauth/authorize

Required Query Parameters

Parameter	Required	Description
client_id	Yes	OAuth client ID.
redirect_uri	Yes	Must exactly match one of the client's registered redirect URIs.
response_type	Yes	Must be code.
scope	Yes	Space-delimited scope list.
state	Yes	Client-provided CSRF protection value.

Optional Query Parameters

Parameter	Description
nonce	Required whenever openid is included in scope.
response_mode	Optional. Supported values: query, fragment, form_post. Defaults to query.
code_challenge	Optional PKCE S256 code challenge. Required when code_challenge_method is present.
code_challenge_method	Optional PKCE challenge method. Supported value: S256. Requires code_challenge.

Example Request

https://portal.eprospera.com/api/oauth/authorize?client_id=...&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&response_type=code&scope=openid%20profile%20email&state=abc123&nonce=xyz789

Success Behavior

After approval, e-Próspera redirects to the registered redirect_uri with:

Parameter	Description
code	Authorization code.
state	Echo of the original state value.

The exact redirect shape depends on response_mode.

Denial Behavior

If the user denies consent, e-Próspera redirects to redirect_uri with:

error=access_denied
state=<original state>

Error Responses

Before the client and redirect URI are validated, the endpoint returns JSON errors.

After the client and redirect URI are validated, recoverable errors redirect back to redirect_uri with error, optional error_description, and the original state. Invalid response_mode values use query for that error redirect.

Missing parameters

{
  "error": "missing_parameters"
}

Invalid response_mode

Redirect to redirect_uri:

error=invalid_request
error_description=Invalid response_mode. Must be one of: query, fragment, form_post
state=<original state>

openid requested without nonce

Redirect to redirect_uri:

error=invalid_request
error_description=nonce is required when requesting openid scope
state=<original state>

code_challenge_method provided without code_challenge

Redirect to redirect_uri:

error=invalid_request
error_description=code_challenge is required when code_challenge_method is provided
state=<original state>

Unsupported code_challenge_method

Redirect to redirect_uri:

error=invalid_request
error_description=code_challenge_method must be S256
state=<original state>

Invalid code_challenge

Redirect to redirect_uri:

error=invalid_request
error_description=code_challenge is invalid
state=<original state>

Invalid response_type

Redirect to redirect_uri:

error=invalid_request
error_description=response_type must be code
state=<original state>

Unknown client or redirect URI mismatch

{
  "error": "invalid_client"
}

Invalid scope request

Redirect to redirect_uri:

error=invalid_scope
error_description=<unsupported or disallowed scopes>
state=<original state>

Server failure

{
  "error": "internal_server_error"
}

Notes

• The portal stores a short-lived consent request and then redirects the user to /consent.
• When entity scopes are requested, the user can choose which legal entities to share.
• Authorization codes are later exchanged at POST /api/oauth/token.