Getting started

Choose an API key or OAuth, then send your first request through the CLI or direct HTTP.

The e-Próspera public API can be used in two ways:

CLI first: use eprospera for shell, CI, and AI-agent workflows.
Direct HTTP: call the REST and OAuth endpoints yourself with curl, an SDK, or your backend client.

Both paths reach the same public API, but the credential depends on whose data you need and what the caller is allowed to do.

Base URL: https://portal.eprospera.com (production). Staging is https://staging-portal.eprospera.com. See Conventions for shared rules.

1. Pick a Credential

Credential	Use it for	Where it works
Standard API key (`sk-`)	Your own backend, hosted checkout, referrals, and personal automation	CLI or direct HTTP
Agent Key (`ak-`)	Delegated, explicitly scoped access for an AI agent, CLI workflow, or third-party service	CLI or direct HTTP
OAuth	A signed-in user's profile, consented legal entities, and personal or entity tax data	Official CLI or your registered OAuth integration

For an API key, sign in to the portal and open Settings > Developer. If you are delegating access, create an Agent Key and grant only the scopes the CLI or agent needs. API keys act as you inside e-Próspera, so store them server-side or in a trusted secret manager and treat them like passwords.

For OAuth data in the official CLI, no key is required. The browser consent screen identifies the requested permissions and lets the user select which legal entities to share.

2. Install the CLI

npm install -g @prospera/eprospera-cli
eprospera --help

To update later, run npm install -g @prospera/eprospera-cli@latest. Published versions are available on npm, with release notes and standalone bundles on GitHub Releases.

For one-off commands, export your key:

export EPROSPERA_API_KEY="ak-..."

For repeated local use, store it with the CLI:

eprospera --api-key "$EPROSPERA_API_KEY" auth login \
  --agent-key \
  --scopes agent:verify_rpn,agent:registry.search

Use --standard-key instead when storing a standard sk-... key.

To authorize the official CLI for user, consented-entity, or tax reads:

eprospera auth login --oauth

The CLI opens a browser for consent, stores rotating tokens securely, refreshes access tokens automatically, and attempts to revoke the remote session on logout.

3. Make Your First CLI Call

The simplest operation is verifying whether a resident permit number (RPN) belongs to a natural person or legal entity:

eprospera --json entity verify 80000000000012

Example response:

{
  "result": "found_legal_entity",
  "active": true
}

The response tells you 80000000000012 belongs to a legal entity with an active residency.

The same workflow can then search for the entity and fetch it:

eprospera --json entity search 80000000000012
eprospera --json entity get <id>

For automation, use --json --yes for write commands and parse stdout as data:

eprospera --json --yes application create --file application.json

4. Read Your Tax and Consented Entity Data

After OAuth login, list the legal entities selected during consent and inspect personal tax obligations:

eprospera --json me legal-entities list
eprospera --json tax status --subject personal
eprospera --json tax list --subject personal --year 2025

Use a returned legal-entity UUID as --subject to read that entity's tax data. These operations are read-only and require the corresponding personal or entity tax scope. See Tax and legal-entity data for the complete access and sensitive-data model.

5. Direct HTTP Alternative

If you are building your own client, send the key as a bearer token:

Authorization: Bearer ak-...

The direct HTTP version of the first request is:

curl -X POST https://portal.eprospera.com/api/v1/verify_rpn \
  -H "Authorization: Bearer <your-api-key-or-agent-key>" \
  -H "Content-Type: application/json" \
  -d '{"rpn": "80000000000012"}'

Use direct HTTP when you need exact wire-level request/response shapes, an OAuth authorization-code flow for your own application, or an endpoint the CLI does not cover. The device flow is currently reserved for the official CLI.

6. Next Steps

CLI guide — install, authenticate, run commands, handle exit codes.
Agent recipes — end-to-end CLI and HTTP workflows for Agent Keys.
Agent Keys guide — delegated scopes, Manifestation of Will, limitations.
Conventions — auth header, response envelopes, errors, timestamps, pagination, rate limits.
Full verify_rpn reference — direct HTTP reference.
Incorporate an LLC — long-form incorporation flow.
OAuth / OIDC overview — let users sign in with their e-Próspera account.
Tax and legal-entity data — consented entities, tax filings, document downloads, and handling guidance.