# e-Próspera API

> Public API and CLI for Próspera's resident registry, legal-entity incorporation, partner-managed natural-person residency, OAuth identity, and agent-delegated workflows. Base URL: https://portal.eprospera.com (production), https://staging-portal.eprospera.com (staging).

The API ships from the same origin as the consumer portal. There is no separate api.eprospera.com host. Prefer the official CLI when a shell command is available; use direct HTTP for custom clients, OAuth flows, and endpoints the CLI does not cover. Credential types: standard API keys (sk-…) for first-party use, Agent Keys (ak-…) for scope-checked delegation, Partner Keys (pk-…) for approved organization-scoped natural-person onboarding, and OAuth 2.0 / OIDC access tokens for end-user consent flows. Conventions (errors, status codes, timestamps, pagination, rate limits) are documented once in /conventions and apply to every endpoint.

## Docs

- [Getting started](https://portal.eprospera.com/api-docs/getting-started): Create an API key, send your first authenticated request.
- [CLI](https://portal.eprospera.com/api-docs/cli): Install `@prospera/eprospera-cli`, authenticate, run JSON-first commands, and handle exit codes.
- [Conventions](https://portal.eprospera.com/api-docs/conventions): Base URL, auth header, response/error envelopes, status codes, timestamps, pagination, rate limits, versioning.
- [Agent Keys](https://portal.eprospera.com/api-docs/agent-keys): Scope-checked delegated access. Read scopes (no MoW required) and write scopes (require active Manifestation of Will).
- [Partner Keys](https://portal.eprospera.com/api-docs/partner-keys): Organization-scoped natural-person residency API, private uploads, hosted applicant consent, platform-only Veriff, rate limits, and idempotency.
- [Skills for AI agents](https://portal.eprospera.com/api-docs/skills-for-agents): CLI-first capability map and decision tree for LLM-based callers.
- [Agent recipes](https://portal.eprospera.com/api-docs/agent-recipes): End-to-end CLI and HTTP chains for RPN lookup, automated LLC incorporation, and account-holder profile reads.
- [Official CLI](https://github.com/Honduras-Prospera-inc/eprospera-cli): Source repository for the e-Próspera CLI.
- [Incorporating an entity](https://portal.eprospera.com/api-docs/incorporating-entity): Five-stage incorporation flow with CLI and direct HTTP examples.
- [Testing in staging](https://portal.eprospera.com/api-docs/testing-in-staging): How to exercise the API against staging.
- [Catalyst Program](https://portal.eprospera.com/api-docs/catalyst-program): Referral attribution.

## OAuth / OIDC

- [OAuth overview](https://portal.eprospera.com/api-docs/oauth-overview): Authorization-code flow with PKCE, refresh tokens.
- [OpenID configuration](https://portal.eprospera.com/api-docs/reference/oauth-openid-configuration): /.well-known/openid-configuration discovery document.
- [JWKS](https://portal.eprospera.com/api-docs/reference/oauth-jwks): RS256 signing keys.
- [Authorization endpoint](https://portal.eprospera.com/api-docs/reference/oauth-authorize): GET /api/oauth/authorize.
- [Token endpoint](https://portal.eprospera.com/api-docs/reference/oauth-token): POST /api/oauth/token (authorization_code, refresh_token).
- [Userinfo endpoint](https://portal.eprospera.com/api-docs/reference/oauth-userinfo): GET /api/oauth/userinfo.

## REST API reference

- [POST /api/v1/verify_rpn](https://portal.eprospera.com/api-docs/reference/post-verify-rpn): Look up an RPN. Rate-limited.
- [POST /api/v1/registries/legal_entities/search](https://portal.eprospera.com/api-docs/reference/post-search-entities): Free-text registry search. Rate-limited.
- [GET /api/v1/legal_entities/{id}](https://portal.eprospera.com/api-docs/reference/get-legal-entities-id): Fetch one legal entity (Agent Keys: API-created only).
- [GET /api/v1/legal_entities/{id}/documents](https://portal.eprospera.com/api-docs/reference/get-legal-entities-id-documents): Fetch entity documents.
- [GET /api/v1/legal_entity_applications](https://portal.eprospera.com/api-docs/reference/get-legal-entity-applications): List your applications.
- [POST /api/v1/legal_entity_applications](https://portal.eprospera.com/api-docs/reference/post-legal-entity-applications): Create an LLC application.
- [GET /api/v1/legal_entity_applications/{id}](https://portal.eprospera.com/api-docs/reference/get-legal-entity-applications-id): Fetch one application; poll for `Approved`/`Rejected`.
- [POST /api/v1/legal_entity_applications/{id}/pay/voucher](https://portal.eprospera.com/api-docs/reference/post-legal-entity-applications-id-pay-voucher): Fully-discount voucher payment.
- [POST /api/v1/legal_entity_applications/{id}/checkout_session](https://portal.eprospera.com/api-docs/reference/post-legal-entity-applications-id-checkout-session): Hosted Stripe / crypto checkout for standard API keys only.
- [POST /api/v1/partner/residency_applications](https://portal.eprospera.com/api-docs/reference/post-residency-applications): Create a partner-owned Draft; requires Idempotency-Key.
- [GET /api/v1/partner/residency_applications](https://portal.eprospera.com/api-docs/reference/get-residency-applications): Cursor-paginated partner-owned applications.
- [GET /api/v1/partner/residency_applications/{id}](https://portal.eprospera.com/api-docs/reference/get-residency-applications-id): Fetch current version, applicant portal state, and next steps.
- [PATCH /api/v1/partner/residency_applications/{id}](https://portal.eprospera.com/api-docs/reference/patch-residency-applications-id): Versioned full-DTO update with AOC invalidation.
- [POST /api/v1/uploads/proof_of_address](https://portal.eprospera.com/api-docs/reference/post-uploads-proof-of-address): Application-bound private PDF/JPEG/PNG upload.
- [GET /api/v1/uploads/proof_of_address/{id}](https://portal.eprospera.com/api-docs/reference/get-uploads-proof-of-address-id): Authenticated private download.
- [POST /api/v1/partner/residency_applications/{id}/checkout_session](https://portal.eprospera.com/api-docs/reference/post-residency-applications-id-checkout-session): Idempotent hosted checkout; response is data.url.
- [POST /api/v1/partner/residency_applications/{id}/pay/voucher](https://portal.eprospera.com/api-docs/reference/post-residency-applications-id-pay-voucher): Idempotent redacted voucher payment.
- `POST /api/v1/partner/residency_applications/{id}/pay/coupon` is a deprecated compatibility alias; use `/pay/voucher` and `voucherCode`.
- [POST /api/v1/partner/residency_applications/{id}/submit](https://portal.eprospera.com/api-docs/reference/post-residency-applications-id-submit): Submit after authenticated hosted AOC, private proof, payment, and portal Veriff.

Partner AOC acceptance and payment operations never submit an application. Submission requires the separately scoped `/submit` endpoint.
- [GET /api/v1/referral-codes/{code}/referrals](https://portal.eprospera.com/api-docs/reference/get-referral-codes-code-referrals): Catalyst referral attribution.

## OAuth-only `/me` endpoints

- [GET /api/v1/me/natural-person](https://portal.eprospera.com/api-docs/reference/oauth-get-natural-person): OAuth or Agent Key (no sk-).
- [GET /api/v1/me/natural-person/id-verification](https://portal.eprospera.com/api-docs/reference/oauth-get-id-verification): Signed-URL artifacts (1 h TTL).
- [GET /api/v1/me/natural-person/residency](https://portal.eprospera.com/api-docs/reference/oauth-get-natural-person-residency): Residency status.
- [GET /api/v1/me/legal-entities](https://portal.eprospera.com/api-docs/reference/oauth-get-legal-entities): OAuth-only — Agent Keys not supported.
- [GET /api/v1/me/legal-entities/{id}](https://portal.eprospera.com/api-docs/reference/oauth-get-legal-entities-id): OAuth-only.
- [GET /api/v1/me/legal-entities/{id}/documents](https://portal.eprospera.com/api-docs/reference/oauth-get-legal-entities-id-documents): OAuth-only.

## Optional

- [llms-full.txt](https://portal.eprospera.com/api-docs/llms-full.txt): Single-file plain-text dump of all endpoints, scopes, request/response shapes, and conventions for agent ingestion.
- [openapi.yaml](https://portal.eprospera.com/api-docs/openapi.yaml): Machine-readable OpenAPI 3.1 spec.

## CLI quick reference

- Install: `npm install -g @prospera/eprospera-cli`
- Auth: `EPROSPERA_API_KEY` or `eprospera --api-key "$EPROSPERA_API_KEY" auth login --agent-key --scopes <csv>`
- Automation shape: `eprospera --json --yes <group> <command>`
- Common commands: `entity verify`, `entity search`, `entity get`, `entity documents`, `application list`, `application create`, `application pay`, `application watch`, `me profile`, `me residency`, `me id-verification`