OAuth 2.0 / OpenID Connect

Capabilities

• Authenticate users with their e-Próspera account
• Receive standard OIDC claims (sub, name, email, picture)
• Obtain refresh tokens for long-lived server access via offline_access
• Fetch user-authorized personal and legal-entity data through the /api/v1/me/* endpoints

Getting credentials

OAuth clients are provisioned per account. If you already have one, you can view the client ID, allowed scopes, and redirect URIs in Settings > Developer.

To request a new client or have your secret re-issued, contact gmembreno@prospera.hn.

Standard endpoints

Reference pages:

• OpenID configuration
• JWKS
• Authorization endpoint
• Token endpoint
• Userinfo endpoint
• Revocation endpoint
• Introspection endpoint

Recommended initial scopes

Start with:

openid profile email

Add offline_access if your backend needs refresh tokens.

Supported scopes

Consent behavior

When you request entity scopes (eprospera:entity.read, eprospera:entity.documents.read), the consent screen lets the user choose which legal entities to share. The access token is limited to that selection.

This means:

• GET /api/v1/me/legal-entities can return an empty array even with a valid token.
• GET /api/v1/me/legal-entities/{id} and /documents only work for consented entity IDs.
• If the user is no longer a representative of an entity, it stops appearing in responses.

Remembered consent

Once a user approves your client, the grant is remembered. Later authorization requests covered by the remembered grant skip the consent screen — the user is redirected straight back to your redirect_uri with a fresh authorization code. Requests for additional scopes show the consent screen again, and you can always force it with prompt=consent.

Revocation from Connected apps

Users can revoke your app's access at any time from portal Settings → Connected apps. Revocation invalidates all of your tokens for that user: access tokens stop working, and refresh attempts fail with invalid_grant. Handle invalid_grant by sending the user back through the authorization flow.

PKCE

All newly registered clients must use PKCE: send code_challenge + code_challenge_method=S256 on the authorization request and the matching code_verifier on the token exchange. Authorization requests from PKCE-required clients without a code challenge fail with error=invalid_request. Existing clients without the flag should adopt PKCE too — it is strongly recommended for every integration.

Client secret rotation

You can request a rotation of your client secret at any time (contact gmembreno@prospera.hn). After a rotation, the old secret keeps working during a grace period so you can deploy without downtime — update your integration to the new secret before the grace period expires.

Resource endpoints

The scopes above unlock these endpoints:

Authorization flow

• response_type=code is required.
• state is required.
• nonce is required when openid is in scope.
• response_mode is optional (query, fragment, or form_post; default query).
• prompt, max_age, and login_hint are supported — see the authorization endpoint reference.
• Every authorization response includes the iss parameter (RFC 9207); validate it against https://portal.eprospera.com.
• Unauthenticated users are redirected to the portal login before returning to the authorization request.

Refresh tokens

Access tokens expire after 1 hour.

If the granted scope set includes offline_access, the token response also includes a refresh_token valid for up to 180 days.

Example refresh request:

curl -X POST https://portal.eprospera.com/api/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=$REFRESH_TOKEN"

Framework guides

• Integration with NextAuth.js
• Integration with Firebase Authentication