# Agent Keys (/agent-keys)

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



## Base URL [#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 [#tldr-for-agents]

* Prefer the [official CLI](/cli) when your runtime can execute shell commands; it wraps the same API with JSON-first commands and stable exit codes.
* 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](/conventions) — endpoint pages do not repeat them.
* For copy-pasteable end-to-end CLI and HTTP workflows (incorporation, profile reads, registry lookups), see [Agent recipes](/agent-recipes).
* CLI source repository: [Honduras-Prospera-inc/eprospera-cli](https://github.com/Honduras-Prospera-inc/eprospera-cli).
* A machine-readable `openapi.yaml` and an `llms-full.txt` summary are published at the docs site root.

## What Agent Keys Are [#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 [#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 [#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 [#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 [#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 [#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 voucher payment to an application

## Authentication Model [#authentication-model]

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

```bash
export EPROSPERA_API_KEY="ak-..."
eprospera --json entity verify 80000000000012

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

With direct HTTP, use Agent Keys like standard API keys:

```bash
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 [#scope-reference]

### Read Scopes [#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 [#write-scopes]

| Scope                             | Description                                         |
| --------------------------------- | --------------------------------------------------- |
| `agent:entity.application.create` | Create legal entity applications                    |
| `agent:entity.application.pay`    | Apply voucher payments to legal entity applications |

## Supported Commands And Endpoints [#supported-commands-and-endpoints]

### Agent-Key Read Commands [#agent-key-read-commands]

| CLI command                         | Direct endpoint                                 | Required Agent Scope                |
| ----------------------------------- | ----------------------------------------------- | ----------------------------------- |
| `eprospera entity verify <rpn>`     | `POST /api/v1/verify_rpn`                       | `agent:verify_rpn`                  |
| `eprospera entity search "<query>"` | `POST /api/v1/registries/legal_entities/search` | `agent:registry.search`             |
| `eprospera entity get <id>`         | `GET /api/v1/legal_entities/{id}`               | `agent:entity.read`                 |
| `eprospera entity documents <id>`   | `GET /api/v1/legal_entities/{id}/documents`     | `agent:entity.documents.read`       |
| `eprospera application list`        | `GET /api/v1/legal_entity_applications`         | `agent:entity.application.read`     |
| `eprospera application get <id>`    | `GET /api/v1/legal_entity_applications/{id}`    | `agent:entity.application.read`     |
| `eprospera me profile`              | `GET /api/v1/me/natural-person`                 | `agent:person.details.read`         |
| `eprospera me residency`            | `GET /api/v1/me/natural-person/residency`       | `agent:person.residency.read`       |
| `eprospera me id-verification`      | `GET /api/v1/me/natural-person/id-verification` | `agent:person.id_verification.read` |

### Agent-Key Write Commands [#agent-key-write-commands]

| CLI command                                                  | Direct endpoint                                           | Required Agent Scope              |
| ------------------------------------------------------------ | --------------------------------------------------------- | --------------------------------- |
| `eprospera --yes application create --file application.json` | `POST /api/v1/legal_entity_applications`                  | `agent:entity.application.create` |
| `eprospera --yes application pay <id> --voucher <code>`      | `POST /api/v1/legal_entity_applications/{id}/pay/voucher` | `agent:entity.application.pay`    |
| `eprospera application watch <id> --timeout 30m`             | `GET /api/v1/legal_entity_applications/{id}`              | `agent:entity.application.read`   |

## Important Limitations [#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/voucher` 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 [#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`:

```json
{
  "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](/conventions#pagination).

## Recommended Usage Pattern [#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, CLI workflow, or third-party service
* **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, OAuth flow, or endpoint integration

## Example [#example]

```bash
eprospera --api-key "ak-REDACTED" --json entity verify 80000000000012
```

The equivalent direct HTTP request is:

```bash
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 CLI and HTTP flows (incorporation, profile reads, registry lookups), see [Agent recipes](/agent-recipes).