> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connections

> How Croma signs in to sources that only answer to a logged-in person: register your own account once, and every query runs as it, with automatic rotation and credentials that are never returned.

Some sources only answer to a signed-in person. [SUNARP](/guides/peru/sunarp),
for example, needs a Peruvian DNI. For those, you register **your own account**
once as a **connection**, and every query of that source runs as it.

<Note>
  You only do this once per account. After that you query the source like any
  other endpoint: nothing extra in the request.
</Note>

## How it fits together

```mermaid theme={"dark"}
flowchart TB
  A["Your app or agent"] -->|"1. register once"| B["Croma API"]
  B -->|"encrypted on arrival"| V[("Connection vault")]
  A -->|"2. query as usual"| B
  B --> S["Isolated sign-in service"]
  V -.->|"opened only here"| S
  S -->|"signed in as your account"| R["Source"]
```

The API that receives your credentials can store them but cannot read them.
Only the isolated service that signs in to the source can open them, and only
for the query that needs them.

## 1. Register a connection

```mermaid theme={"dark"}
sequenceDiagram
  autonumber
  participant App as Your app
  participant API as Croma API
  participant Src as Source
  App->>API: POST /pe/sunarp/connections/v1<br/>account fields + authorized: true
  API->>API: encrypt, bound to your organization
  API->>Src: sign in once to check the account
  alt the source accepts it
    API-->>App: 201 { id: "conn_…", display_name: "J*** P*** G***" }
  else the source turns it down
    API-->>App: 422 connection_rejected (nothing is kept)
  end
```

`authorized: true` records that you own the account or have its owner's
authorization. The answer never includes the credentials, only a masked name.

## 2. Query

```mermaid theme={"dark"}
sequenceDiagram
  autonumber
  participant App as Your app
  participant API as Croma API
  participant Src as Source
  App->>API: POST /pe/sunarp/registry-search/v1
  alt asked in the last 30 days
    API-->>App: 200 from Croma, nothing sent to the source
  else new question
    API->>API: pick one of your connections
    API->>Src: query, signed in as that account
    Src-->>API: answer
    API-->>App: 200 { data }
  end
```

* **Picking.** Croma prefers the connection whose session is already open, then
  the one with the most allowance left. Send `connection_id` to use a specific
  one.
* **One query per account at a time.** Queries on different accounts run in
  parallel; queries on the same account wait their turn, so they never sign in
  over each other.
* **Rotation.** When an account reaches its daily allowance, the same query
  moves to your next connection. Register more than one for more capacity.

## Connection states

```mermaid theme={"dark"}
stateDiagram-v2
  [*] --> active: registered and checked
  active --> exhausted: daily allowance used
  exhausted --> active: allowance resets
  active --> invalid: the source no longer accepts it
  invalid --> [*]: delete it and register again
  active --> [*]: DELETE
```

`GET /pe/sunarp/connections/v1` shows each connection's state, the sign-ins
used today and when it resets.

| Status | Code | When |
| - | - | - |
| 409 | `connection_required` | Your organization has no connection for the source yet. |
| 422 | `connection_rejected` | The source no longer accepts the account. |
| 429 | `connections_exhausted` | Every connection used its daily allowance. `Retry-After` says when one is back. |

## Security

* Credentials are encrypted as soon as they reach Croma and bound to your
  organization: they cannot be used by anyone else's.
* Only the isolated service that signs in to the source can open them.
* They are never returned by the API or shown to anyone, and never written to
  logs.
* Deleting a connection destroys it permanently.

## From an agent (MCP)

The same verbs are tools on the [MCP server](/mcp-server): `sunarp_connect`,
`sunarp_list_connections` and `sunarp_delete_connection`. An agent can connect
the user's account in conversation, with their consent, and then query.

<Card title="SUNARP" icon="building-columns" href="/guides/peru/sunarp">
  The first source that uses connections, with its fields and examples.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.