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

The endpoint can return JSON errors before any redirect occurs.

Missing parameters

{
  "error": "missing_parameters"
}

Invalid response_mode

{
  "error": "invalid_request",
  "error_description": "Invalid response_mode. Must be one of: query, fragment, form_post"
}

openid requested without nonce

{
  "error": "invalid_request",
  "error_description": "nonce is required when requesting openid scope"
}

code_challenge_method provided without code_challenge

{
  "error": "invalid_request",
  "error_description": "code_challenge is required when code_challenge_method is provided"
}

Unsupported code_challenge_method

{
  "error": "invalid_request",
  "error_description": "code_challenge_method must be S256"
}

Invalid code_challenge

{
  "error": "invalid_request",
  "error_description": "code_challenge is invalid"
}

Unknown client or redirect URI mismatch

{
  "error": "invalid_client"
}

Invalid scope request

{
  "error": "invalid_scope",
  "error_description": "eprospera:entity.documents.read"
}

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.