# Add "Sign in with e-Próspera" to your app (/use-cases/sign-in-with-eprospera)

Authenticate users with OAuth 2.0 / OpenID Connect and, with their consent, read verified residency and entity data.



You build a SaaS product, a community platform, or a fintech app, and you want users to sign in with their e-Próspera account — optionally proving they are a verified Próspera resident or entity owner.

**Credential:** an OAuth client (client ID + secret), created by the e-Próspera team. The flow is standard authorization-code with PKCE (required), documented end to end in the [OAuth overview](/oauth-overview).

## Two integration tiers [#two-integration-tiers]

**Tier 1 — login and identity.** Request `openid profile email`. You get a standards-compliant OIDC login with signed ID tokens — enough for authentication.

**Tier 2 — verified residency data.** Additionally request `eprospera:person.details.read`, `eprospera:person.residency.read`, `eprospera:person.id_verification.read`, or the `eprospera:entity.*` scopes. With the user's consent you can then read their residency status, ID-verification state, and consented legal entities — turning "sign in" into "prove you're a resident."

## The flow [#the-flow]

1. **Authorize** — redirect to [GET /api/oauth/authorize](/reference/oauth-authorize) with PKCE (`S256`), `state`, and (for `openid`) a `nonce`. Users see a consent screen; approved consent is remembered for repeat visits.
2. **Exchange the code** — [POST /api/oauth/token](/reference/oauth-token). Access tokens live 1 hour; request `offline_access` for 180-day refresh tokens.
3. **Read the user** — [GET /api/oauth/userinfo](/reference/oauth-userinfo) returns the standard claims plus `eprospera:rpn` for verified residents.
4. **Read consented resources** — [natural person](/reference/oauth-get-natural-person) · [residency](/reference/oauth-get-natural-person-residency) · [ID verification](/reference/oauth-get-id-verification) · [legal entities](/reference/oauth-get-legal-entities) and their [documents](/reference/oauth-get-legal-entities-id-documents).

Discovery, keys, and token hygiene: [openid-configuration](/reference/oauth-openid-configuration) · [JWKS](/reference/oauth-jwks) · [revoke](/reference/oauth-revoke) · [introspect](/reference/oauth-introspect).

<Callout title="Per-entity consent" type="info">
  Users choose which of their legal entities to share during consent — `GET
    /api/oauth/me/legal-entities` can legitimately return an empty list even for
  an entity owner. Design your UI for partial consent.
</Callout>

## Framework quickstarts [#framework-quickstarts]

* [NextAuth.js / Auth.js](/oauth-nextauth) — custom OIDC provider in \~20 lines
* [Firebase Authentication](/oauth-firebase) — e-Próspera as an OpenID Connect provider

## What this API does not do [#what-this-api-does-not-do]

* No implicit or password grants — authorization-code + PKCE only.
* No user data without consent; scopes are enforced per token.
* Users can revoke your app anytime from their portal's Connected Apps — handle `invalid_grant` on refresh gracefully.

## Next steps [#next-steps]

* [OAuth overview](/oauth-overview) — scopes, consent, PKCE, token lifetimes
* [Conventions](/conventions) — error envelope and status codes