# Getting started (/getting-started)

Create an API key and send your first authenticated request — CLI-first 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 use the same credentials and permissions.

**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]

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](https://portal.eprospera.com/settings). 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 [#2-install-the-cli]

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

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.

## 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. Direct HTTP Alternative [#4-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, OAuth authorization-code flows, or an endpoint the CLI does not cover.

## 5. Next Steps [#5-next-steps]

* [CLI guide](/cli) — install, authenticate, run commands, handle exit codes.
* [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.