Getting started

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 use the same credentials and permissions.

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

1. Pick a Credential

There are two API key models:

• Standard API keys (sk-) for your own backend or personal automation.
• Agent Keys (ak-) for delegated access to a specific AI agent, CLI workflow, or third-party service, with explicit scopes.

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. Store them server-side or in a trusted secret manager, and treat them like passwords.

2. Install the CLI

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

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.

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. 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, OAuth authorization-code flows, or an endpoint the CLI does not cover.

5. 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.