e-Próspera API

Appearance

OAuth 2.0 / OpenID Connect ​

e-Próspera provides an OAuth 2.0 and OpenID Connect authorization server so third-party applications can authenticate users and access their data with consent.

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 ​

EndpointURL
OpenID configurationhttps://portal.eprospera.com/.well-known/openid-configuration
JWKShttps://portal.eprospera.com/api/oauth/.well-known/jwks.json
Authorization endpointhttps://portal.eprospera.com/api/oauth/authorize
Token endpointhttps://portal.eprospera.com/api/oauth/token
Userinfo endpointhttps://portal.eprospera.com/api/oauth/userinfo

Reference pages:

Start with:

text
openid profile email

Add offline_access if your backend needs refresh tokens.

Supported scopes ​

ScopeDescription
openidAuthenticate the user with e-Próspera.
profileRead the user's name and profile picture.
emailRead the user's email address.
offline_accessReceive a refresh token for background access-token renewal.
eprospera:person.details.readRead detailed natural-person profile data.
eprospera:person.residency.readRead the user's current residency status.
eprospera:person.id_verification.readRead the latest approved identity-verification images.
eprospera:entity.readRead legal-entity data for entities the user consents to share.
eprospera:entity.documents.readRead legal-entity documents for consented entities.

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.

Resource endpoints ​

The scopes above unlock these endpoints:

EndpointRequired scope
GET /api/v1/me/natural-personeprospera:person.details.read
GET /api/v1/me/natural-person/residencyeprospera:person.residency.read
GET /api/v1/me/natural-person/id-verificationeprospera:person.id_verification.read
GET /api/v1/me/legal-entitieseprospera:entity.read
GET /api/v1/me/legal-entities/[id]eprospera:entity.read
GET /api/v1/me/legal-entities/[id]/documentseprospera:entity.documents.read

INFO

/api/v1/me/natural-person/id_verification (underscore) exists as a compatibility alias. Use /id-verification (hyphen) for new integrations.

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).
  • 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:

bash
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"

WARNING

Refresh tokens rotate on every successful refresh. Always persist the newest refresh_token from the response. You may request a reduced scope set on refresh, provided it is a subset of the originally granted scopes.

Framework guides ​