# e-Próspera API

> Public API for Próspera's resident registry, legal-entity incorporation, 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. Three credential types: standard API keys (sk-…) for first-party use, Agent Keys (ak-…) for scope-checked AI/third-party delegation, 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.
- [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).
- [Skills for AI agents](https://portal.eprospera.com/api-docs/skills-for-agents): Capability map and decision tree for LLM-based callers. Read first to avoid empty/wrong endpoints.
- [Agent recipes](https://portal.eprospera.com/api-docs/agent-recipes): End-to-end curl chains for RPN lookup, automated LLC incorporation (coupon and hosted-checkout flavors), and account-holder profile reads.
- [Incorporating an entity](https://portal.eprospera.com/api-docs/incorporating-entity): Five-stage incorporation flow with full curl 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/coupon](https://portal.eprospera.com/api-docs/reference/post-legal-entity-applications-id-pay-coupon): Fully-discount coupon 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.
- [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.