# Getting started (/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](/conventions) for shared rules.

## 1. Pick a Credential [#1-pick-a-credential]

| Credential                                 | Use it for                                                                                | Where it works                                    |
| ------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------- |
| [Standard API key](/standard-keys) (`sk-`) | Your own backend, hosted checkout, referrals, and personal automation                     | CLI or direct HTTP                                |
| [Agent Key](/agent-keys) (`ak-`)           | Delegated, explicitly scoped access for an AI agent, CLI workflow, or third-party service | CLI or direct HTTP                                |
| [Partner Key](/partner-keys) (`pk-`)       | Approved organization onboarding of natural-person applicants                             | 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
[Developer → API keys](https://portal.eprospera.com/developer/api-keys). 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 [#2-install-the-cli]

```bash
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](https://www.npmjs.com/package/@prospera/eprospera-cli),
with release notes and standalone bundles on
[GitHub Releases](https://github.com/Honduras-Prospera-inc/eprospera-cli/releases).

For one-off commands, export your key:

```bash
export EPROSPERA_API_KEY="ak-..."
```

For repeated local use, store it with the CLI:

```bash
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:

```bash
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 [#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:

```bash
eprospera --json entity verify 80000000000012
```

Example response:

```json
{
  "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:

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

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

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

## 4. Read Your Tax and Consented Entity Data [#4-read-your-tax-and-consented-entity-data]

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

```bash
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](/tax-and-entity-data) for the complete
access and sensitive-data model.

## 5. Direct HTTP Alternative [#5-direct-http-alternative]

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

```text
Authorization: Bearer ak-...
```

The direct HTTP version of the first request is:

```bash
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 [#6-next-steps]

* [CLI guide](/cli) — install, authenticate, run commands, handle exit codes.
* [Standard API Keys](/standard-keys) — first-party `sk-` keys: what you can read, write, and cannot access.
* [Agent recipes](/agent-recipes) — end-to-end CLI and HTTP workflows for Agent Keys.
* [Agent Keys guide](/agent-keys) — delegated scopes, Manifestation of Will, limitations.
* [Conventions](/conventions) — auth header, response envelopes, errors, timestamps, pagination, rate limits.
* [Full `verify_rpn` reference](/reference/post-verify-rpn) — direct HTTP reference.
* [Incorporate an LLC](/incorporating-entity) — long-form incorporation flow.
* [OAuth / OIDC overview](/oauth-overview) — let users sign in with their e-Próspera account.
* [Tax and legal-entity data](/tax-and-entity-data) — consented entities, tax filings, document downloads, and handling guidance.