Agent Keys

Agent Keys let an e-resident delegate specific API capabilities to an AI agent or third-party service without sharing their personal standard API key.

Base URL

Environment	Origin
Production	https://portal.eprospera.com
Staging	https://staging-portal.eprospera.com

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 for agents

• Send the key as Authorization: Bearer ak-... on every request.
• Every endpoint is scope-checked; missing scope returns 403.
• Shared rules (errors, status codes, timestamps, rate limits, pagination) are documented once in Conventions — endpoint pages do not repeat them.
• For copy-pasteable end-to-end workflows (incorporation, profile reads, registry lookups), see Agent recipes.
• A machine-readable openapi.yaml and an llms-full.txt summary are published at the docs site root.

What Agent Keys Are

• Standard API keys (sk-) are still for personal or first-party use. They are not scoped and should not be shared.
• Agent Keys (ak-) are created by the account owner in the e-Próspera settings UI and can only do the actions the owner explicitly selects.
• Agent Keys are additive. Existing standard API key behavior does not change.

Who Can Create Them

Only the e-resident who owns the account can create an Agent Key in the portal settings page.

This means Agent Key access is not public and not open to arbitrary third parties:

• The account owner must create the key
• The account owner must choose the scopes
• The account owner must deliver the key to the service or agent they trust
• The key only acts on behalf of that account, within the granted scopes

Manifestation of Will

Write-capable Agent Keys require an active signed Manifestation of Will.

• Read-only Agent Keys can be created without it
• Any Agent Key with a write scope requires it
• Revoking the Manifestation of Will automatically revokes linked write-capable Agent Keys

The Manifestation of Will is signed in the same Developer settings area where Agent Keys are managed.

Agreement of Coexistence (AOC) Acceptance

When signing the Manifestation of Will, you can optionally also accept one or more Legal Entity Agreements of Coexistence (for Resident and/or e-Resident entities). If you do, agents using your key can create legal entity applications without requiring a separate browser-based signature step — the AOC acceptance is applied automatically from your stored acceptance.

This is what enables fully automated entity incorporation via Agent Keys. Without pre-accepted AOCs, the API returns a nextSteps.signature URL that requires manual interaction.

You can also accept additional AOCs later from the Developer settings without re-signing the Manifestation of Will.

Drip Emails

After signing the Manifestation of Will, you will receive a confirmation email. Additionally, you will receive a weekly reminder email every Monday as long as you have active write-capable Agent Keys. This email summarizes your active keys, recent agent activity, and reminds you of your legal responsibility to monitor or revoke keys you are no longer using.

Audit Logs And Notifications

All Agent Key requests are audited.

Successful write actions also trigger email notifications to the account owner. Currently, notifications are sent when an Agent Key:

• creates a legal entity application
• applies a coupon payment to an application

Authentication Model

Use Agent Keys like standard API keys:

Authorization: Bearer ak-...

Agent Keys are scope-checked. A request fails with 403 if the key does not include the required scope.

Standard API keys continue to work on the standard API routes that already supported them.

Scope Reference

Read Scopes

Scope	Description
agent:person.details.read	Read personal details such as name, resident permit number, date of birth, address, and phone number
agent:person.residency.read	Read current residency status and residency type
agent:person.id_verification.read	Read identity-verification document URLs and selfie artifacts
agent:entity.read	Read legal entity details for entities you represent
agent:entity.documents.read	Read legal entity documents for entities you represent
agent:entity.application.read	Read your API-created legal entity applications
agent:verify_rpn	Verify whether an RPN exists and is active
agent:registry.search	Search the legal-entity registry by name or RPN

Write Scopes

Scope	Description
agent:entity.application.create	Create legal entity applications
agent:entity.application.pay	Apply coupon payments to legal entity applications

Supported Endpoints

Agent-Key Read Endpoints

Endpoint	Required Agent Scope
POST /api/v1/verify_rpn	agent:verify_rpn
POST /api/v1/registries/legal_entities/search	agent:registry.search
GET /api/v1/legal_entities/{id}	agent:entity.read
GET /api/v1/legal_entities/{id}/documents	agent:entity.documents.read
GET /api/v1/legal_entity_applications	agent:entity.application.read
GET /api/v1/legal_entity_applications/{id}	agent:entity.application.read
GET /api/v1/me/natural-person	agent:person.details.read
GET /api/v1/me/natural-person/residency	agent:person.residency.read
GET /api/v1/me/natural-person/id-verification	agent:person.id_verification.read

Agent-Key Write Endpoints

Endpoint	Required Agent Scope
POST /api/v1/legal_entity_applications	agent:entity.application.create
POST /api/v1/legal_entity_applications/{id}/pay/coupon	agent:entity.application.pay

Important Limitations

• Agent Keys do not replace OAuth for consent-based legal-entity sharing flows
• /api/v1/me/legal-entities* remains OAuth-only
• There is currently no /api/v1/legal_entities list endpoint for Agent Keys; use known entity IDs with GET /api/v1/legal_entities/{id} and GET /api/v1/legal_entities/{id}/documents
• /api/v1/me/natural-person* accepts OAuth access tokens or Agent Keys, but not standard API keys
• Agent-key reads for /api/v1/legal_entity_applications* are limited to applications created through the API (createdViaAPI: true)
• Agent Key checkout-session creation is temporarily disabled; use POST /api/v1/legal_entity_applications/{id}/pay/coupon or have the resident pay through the portal
• Other existing standard-key routes that were not explicitly enabled for Agent Keys remain standard-key only

Pagination

List endpoints accessible to Agent Keys (GET /api/v1/legal_entity_applications, GET /api/v1/legal_entities/{id}/documents) are not currently paginated — the full result set is returned under data in a single response. There are no ?page / ?cursor parameters today.

When pagination ships, it will mirror the envelope already used on /api/v1/nomadlayer/applications:

{
  "data": [
    /* ... */
  ],
  "pagination": { "page": 1, "pageSize": 20, "totalCount": 134, "pageCount": 7 }
}

Design clients so adding a top-level pagination field will not break them. See Conventions → Pagination.

Recommended Usage Pattern

Use:

• OAuth when your integration needs interactive user consent and identity login
• Standard API keys (sk-) for your own backend or personal automation
• Agent Keys (ak-) when an e-resident is delegating narrowly scoped access to an AI agent or third-party service

Example

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

If the Agent Key includes agent:verify_rpn, the request succeeds. Otherwise the API returns 403.

For end-to-end multi-step flows (incorporation, profile reads, registry lookups), see Agent recipes.