Standard API Keys

Base URL

All endpoint paths in this document are relative to that origin. The API ships from the same host as the consumer portal — there is no separate api.eprospera.com.

TL;DR

• Create a key in Developer → API keys. The raw sk-... value is shown once.
• Send it as Authorization: Bearer sk-... on every request, or store it for the official CLI.
• Standard keys are not scoped. They can call every standard-key route as the account owner. Do not share them with an agent or third party — use an Agent Key (ak-) for that.
• Writes do not require a Manifestation of Will. The Agreement of Coexistence still needs a browser signature unless you switch to an Agent Key with a pre-accepted AOC.
• Voucher payment and hosted checkout only work on API-created Draft applications. You can still list portal-created applications.
• Shared rules (errors, status codes, timestamps, rate limits, pagination) are documented once in Conventions.
• CLI source repository: Honduras-Prospera-inc/eprospera-cli.

What Standard API Keys Are

A standard API key is the personal, first-party credential for the account that created it. It is the default key type in Developer settings.

Standard keys are additive with Agent Keys. Creating an ak- key does not change what an sk- key can do.

Who Can Create Them

Only the signed-in account owner can create a standard API key.

• Open Developer → API keys
• Give the key a label (1–50 characters)
• Optionally list allowed checkout origins (comma-separated origins such as https://app.example.com) if you will create hosted checkout sessions. Origins must be HTTPS (HTTP is allowed only for loopback in staging/dev), with no path, query, fragment, or credentials. At most 10 origins.
• Copy the sk-... value immediately — e-Próspera stores only a SHA-256 hash and a short prefix (sk- plus four characters)
• Delete the key in the same settings page to revoke it immediately

Standard keys do not expire on a timer. Partner Keys expire after 90 days; standard keys stay valid until you delete them.

Authentication

With the CLI, pass the key once per command or store it locally:

export EPROSPERA_API_KEY="sk-..."
eprospera --json entity verify 80000000000012

eprospera --api-key "$EPROSPERA_API_KEY" auth login --standard-key
eprospera --json auth whoami

With direct HTTP:

Authorization: Bearer sk-...

There is no scope header and no Manifestation of Will. If the key is valid, the request is authorized as the owner. A missing or unknown key returns 401. Partner Keys (pk-) are not accepted on these routes. An Agent Key on a standard-key-only route such as referrals returns 403; hosted checkout currently returns 503 for Agent Keys.

CLI With a Standard Key

Install once, then prefer JSON output for anything you will parse:

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

Useful inspection commands that work with a stored standard key:

eprospera --json auth whoami
eprospera --json config list
eprospera schema

Visitor-pass submission is a public CLI/API flow and does not use the key. See event visitor passes and eprospera --json --yes visitor-pass create.

What Information You Can Pull

This is the first-party read surface. Standard keys never return another person's profile, residency, ID-verification artifacts, or tax records.

Response envelopes differ by endpoint: verify returns a flat { "result", "active" } object, search returns { "results": [...] }, and the rest wrap a single resource or array in { "data": ... }. See Conventions.

Public registry lookups

These two endpoints look up any known RPN or registered legal entity. They do not require that you represent the subject. Search is a case-insensitive name match and a partial RPN match. The query string must be 1–100 characters after trim.

RPNs are 14-digit numeric strings: legal entities start with 8, natural persons with 9. verify_rpn does not return a name, UUID, address, or documents — only whether the RPN exists and whether that residency is currently active. Use search when you need an entity UUID.

Both endpoints are rate-limited to 5,000 requests / 24 h and 50 / minute per API key. Other standard-key routes have no documented limit today.

Legal entities you represent

Once you have an entity UUID, you can read the full record and its public documents only if you are a current representative. Unlike Agent Keys, this includes entities formed in the portal, not only records created through the API.

principalOfficeAddress is an address object (line1, optional line2, city, optional state, postalCode, country) or null. Dates are ISO 8601 UTC strings, or null when unknown. Document fileUrl can be null; slug and version are optional.

A 404 means the entity does not exist or you are not a representative — the two are indistinguishable. There is no GET /api/v1/legal_entities list endpoint.

Entity applications you own

Standard keys list and read every legal-entity application on the account, including drafts created in the portal. Agent Keys only see applications with createdViaAPI: true.

Each application object includes:

There is currently no pagination — the full list is returned under data.

Listing a portal-created application does not mean you can pay it through the API. Voucher payment and hosted checkout reject applications that were not created via POST /api/v1/legal_entity_applications.

Catalyst referrals you own

Referral attribution is standard-key only. Agent Keys cannot call this route.

You can only query a code that belongs to you (your personal code, or a code owned by an entity you represent). fullName is null until the referred person has applied or been approved. Legal-entity referredAt can be null. The response reports attribution only — not invoice or discount state. See Catalyst Program.

What a standard key cannot read

Create, Pay, and Watch

The full tutorial is Incorporating an entity. This section is the standard-key contract.

The key owner must be an active e-Resident or Resident. POST /api/v1/legal_entity_applications is not idempotent — retrying can create a duplicate Draft. Validate locally first:

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

Create request

Provide exactly one registered-agent mode: registeredAgentProvider or registeredAgentDetails, not both and not neither.

Create response

The body is { "data": { …application }, "nextSteps": { "signature": "<url-or-null>" } }.

For a standard key, nextSteps.signature is the portal URL where the owner signs the Agreement of Coexistence. Standard keys do not carry a Manifestation of Will, so they cannot skip this browser step. Payment and signature can happen in either order; the application leaves Draft only after both are complete.

Pay with a voucher

eprospera --json --yes application pay <id> --voucher FOUNDER100

curl -X POST https://portal.eprospera.com/api/v1/legal_entity_applications/<id>/pay/voucher \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"voucherCode": "FOUNDER100"}'

The voucher must fully cover the invoice. The application must be a Draft created through the API. If the AOC is already signed, payment also submits. If it is not signed yet, the endpoint still succeeds with statusId: "Draft" and a reminder message. Envelope: { "success": true, "data": { … }, "message": "..." }.

In staging, the reusable test voucher is API1234. It applies to every product and unpaid invoice, not only entity incorporation. See Testing in staging.

The deprecated alias POST /api/v1/legal_entity_applications/{id}/pay/coupon accepts { "couponCode": "..." }; use the voucher path instead.

Hosted checkout (sk- only)

Agent Keys cannot create checkout sessions (they currently get 503). With a standard key:

eprospera --json --yes application checkout <application-id> \
  --redirect-url https://example.com/return \
  --provider stripe

{
  "paymentProvider": "stripe",
  "redirectUrl": "https://example.com/return",
  "email": "contact@example.com"
}

Send exactly one of paymentProvider or paymentMethod. Supported paymentProvider values: stripe, stripe-crypto, blink, blink-onchain, solana-pay-ptc. email is optional. redirectUrl is required and its origin must be on the key's allowed checkout origins.

The application must be an API-created Draft with an unpaid open invoice. Response: { "data": { /* provider payload */ }, "invoiceId": "<uuid>" }. Send the user to the returned checkout URL, then poll.

In staging, complete Stripe checkout with card ACCT-000015 (any future expiry, any CVC and ZIP). See Testing in staging.

See hosted checkout.

Watch until a terminal status

There are no public webhooks. Prefer the CLI watcher, or poll GET /api/v1/legal_entity_applications/{id} every 30 seconds for the first 2 minutes, then every 5 minutes.

eprospera --json application watch <id> --timeout 30m

Approved and Rejected are the only terminal statusId values. After Approved, legalEntityId is set — fetch the entity and its documents.

A declined or abandoned checkout does not add a payment-failure statusId; the application stays Draft. Stop polling, then retry payment or apply a voucher. The CLI watcher exits 10 for that case.

Supported Commands And Endpoints

Reads

Writes

Important Limitations

• /api/v1/me/* does not accept standard API keys — including profile, residency, ID verification, consented entities, and tax
• There is no /api/v1/legal_entities list endpoint; resolve UUIDs through registry search or from applications you own
• GET /api/v1/legal_entities/{id} only returns entities you currently represent
• Voucher payment and hosted checkout cannot be used on portal-created applications
• Partner residency routes (/api/v1/partner/*) reject sk- keys
• Visitor-pass submission is public and does not use a key
• Standard-key requests are not written to the Agent Key audit log and do not email the owner on writes
• Treat the key like a password: store it server-side or in a secret manager, never in a browser, repo, or chat

Common Errors

CLI exit codes for the same failures are documented in CLI → Exit Codes (3 auth, 4 authorization, 5 not found, 6 conflict, 7 rate limit, 8 validation).

Recommended Usage Pattern

Use:

• Standard API keys (sk-) for your own backend, CLI, hosted checkout, referrals, and personal automation
• Agent Keys (ak-) when an e-resident is delegating narrowly scoped access to an AI agent or third-party service
• Partner Keys (pk-) when an approved organization is onboarding natural-person applicants
• OAuth when your integration needs interactive user consent, identity login, or tax data
• The CLI when a shell command is acceptable and you want JSON output, local validation, polling, and stable exit codes
• Direct HTTP when you are building a custom client or need an endpoint the CLI does not cover

Example

eprospera --api-key "sk-REDACTED" --json entity verify 80000000000012
eprospera --api-key "sk-REDACTED" --json entity search 80000000000012
eprospera --api-key "sk-REDACTED" --json entity get <id>

The equivalent direct HTTP requests are:

curl -X POST https://portal.eprospera.com/api/v1/verify_rpn \
  -H "Authorization: Bearer sk-REDACTED" \
  -H "Content-Type: application/json" \
  -d '{"rpn": "80000000000012"}'

curl -X POST https://portal.eprospera.com/api/v1/registries/legal_entities/search \
  -H "Authorization: Bearer sk-REDACTED" \
  -H "Content-Type: application/json" \
  -d '{"query": "80000000000012"}'

curl https://portal.eprospera.com/api/v1/legal_entities/<id> \
  -H "Authorization: Bearer sk-REDACTED"

Reference

• POST verify_rpn
• POST registries/legal_entities/search
• GET legal_entities/{id}
• GET legal_entities/{id}/documents
• GET legal_entity_applications
• POST legal_entity_applications
• GET legal_entity_applications/{id}
• POST …/pay/voucher
• POST …/checkout_session
• GET referral-codes/{code}/referrals
• Incorporating an entity
• CLI
• Testing in staging