OAuth 2.0 / OpenID Connect Integration

e-Próspera provides an OAuth 2.0 and OpenID Connect (OIDC) compliant authorization server that allows third-party applications to access user data with explicit user consent.

Overview

The OAuth integration enables applications to:

• Authenticate users via their e-Próspera account (OpenID Connect)
• Access basic user information (name, email, photo)
• Access personal information (full legal name, resident permit number, country of birth, citizenships, date of birth, sex, address, and phone number)
• Retrieve verified identity documents for KYC
• Access residency status

Getting Started

1. Receiving OAuth Credentials

To integrate with e-Próspera's OAuth, you'll need to:

1. Contact e-Próspera to register your application (email: gmembreno@prospera.hn)
2. Provide your redirect URIs
   • For Firebase, this will be something like https://[your-project-id].firebaseapp.com/__/auth/handler
   • For NextAuth, it will be something like https://[your-domain]/api/auth/callback/eprospera
3. Specify required scopes
4. Receive your client_id and client_secret

2. Integrating with your framework

If you're using one of the following frameworks, you can follow our guides:

• Integration with NextAuth.js
• Integration with Firebase Authentication

If your framework of choice is not listed, here are the standard OAuth 2.0 endpoints:

Endpoint	URL
Well-known	https://portal.eprospera.com/.well-known/openid-configuration
JWKS	https://portal.eprospera.com/api/oauth/.well-known/jwks.json
Authorization Endpoint	https://portal.eprospera.com/api/oauth/authorize
Token Endpoint	https://portal.eprospera.com/api/oauth/token
Userinfo Endpoint	https://portal.eprospera.com/api/oauth/userinfo

Choosing these default scopes is recommended:

openid profile email

They'll give you access to the user's name, email, and profile picture. If your backend needs long-lived API access, add offline_access as well.

3. Scopes

Once you have a basic integration working, you can start requesting additional scopes:

Scope	Description
openid profile email	View your name, email, and profile picture
offline_access	Receive a refresh token so your backend can renew access tokens without sending the user back through the login flow
eprospera:person.details.read	Access to personal information: full legal name, resident permit number, country of birth, citizenships, date of birth, sex, address, and phone number
eprospera:person.residency.read	Access to user's residency type, effective date, and expiration date
eprospera:person.id_verification.read	Access to a copy of the ID document + selfie the resident uploaded to Veriff when completing Identity Verification on e-Próspera
eprospera:entity.read	Access to legal entity information for entities the user represents. During authorization, the user selects which specific entities to share.
eprospera:entity.documents.read	Access to legal entity documents (Certificate of Organization, Rider to Agreement of Coexistence, etc.) for consented entities

These scopes will let you query the following endpoints, on behalf of the user:

• GET me/natural-person (eprospera:person.details.read)
• GET me/natural-person/id_verification (eprospera:person.id_verification.read)
• GET me/legal-entities (eprospera:entity.read)
• GET me/legal-entities/[id] (eprospera:entity.read)
• GET me/legal-entities/[id]/documents (eprospera:entity.documents.read)

4. Refresh Tokens

Access tokens expire after 1 hour. If you request offline_access, the token response will also include a refresh_token that stays valid for 180 days.

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email offline_access",
  "refresh_token": "rt_..."
}

To refresh an access token, call the same token endpoint with grant_type=refresh_token:

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"

Every refresh rotates the refresh token. Always replace the stored refresh token with the newest value returned by the server.