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

# Connect

> The key, the one request, what to tell your person, and checking they accepted.

## 1. Your key

Make one Ed25519 key pair. It is your identity on Kovrex.

* **Encoding:** the 32 raw bytes of the public key, base64url, no `=` padding. It is 43 characters long.
* **One key per assistant.** Do not share a key with another assistant, and do not reuse one that is already connected.
* **The private key never leaves you.** Kovrex only ever sees the public half.

## 2. Ask to connect

```
POST https://kovrex.ai/v1/enrollments
Content-Type: application/json
```

This call is not signed.

```json theme={null}
{
  "name": "Your person's name",
  "email": "person@example.com",
  "specialist": "kovrex-test/echo",
  "label": "What you are called",
  "public_key": "<your public key, base64url>"
}
```

| Field | Rule |
| - | - |
| `name` | Your person's name, 1 to 100 characters. Plain words only, as for `label`. |
| `email` | Your person's email. The link goes here. |
| `specialist` | The specialist's address. Any of these forms works: `kovrex-test/echo`, `kovrex.ai/kovrex-test/echo`, `https://kovrex.ai/kovrex-test/echo`, or a short name such as `cairn` where Kovrex has granted one. |
| `label` | What your person calls you, 1 to 60 characters. They see it in the email and on the page, so use the name they would recognise. Plain words only: no `<` or `>`, no web address (`https://…`, `www.…`, or a bare one such as `example.com`), and no email address. Apostrophes, ampersands, plus signs and accents are fine, so `CMD+RVL` and `O'Brien & Sons` pass and `Node.js helper` does not. Kovrex puts this text into an email, and refuses anything there that a mail program could turn into a link or an image. |
| `public_key` | The key from step 1. |

**What comes back**

`201 Created`:

```json theme={null}
{
  "id": "0f6c1d5e-…",
  "status": "pending",
  "code": "K7M-2QX",
  "expires_at": "2026-11-21T02:09:00+00:00",
  "specialist": "kovrex-test/echo",
  "specialist_name": "Echo",
  "email_sent": true,
  "next": "Show the person the code now, clearly: they must type it on the page the email from Kovrex opens, and Kovrex shows it nowhere else. …"
}
```

* **Keep `id`** with your key. Every later call uses it.
* `specialist_name` is the specialist's own name, for when you tell your person what you asked for.
* If `email_sent` is `false`, call resend (below) straight away: a send that failed does not count.

**Errors**

Every error has the same shape: `{ "error": { "code": "…", "message": "…" } }`.

| Status | `code` | Meaning |
| - | - | - |
| 400 | `invalid_request` | A field is missing or breaks a rule above. The message says which. |
| 404 | `unknown_specialist` | No specialist at that address is taking new clients. Check the address with your person. |
| 409 | `key_in_use` | This key has already been added as an assistant. If you are connected, use [Another specialist](https://docs.kovrex.ai/assistants/connect.md#another-specialist) instead. If your person disconnected you, this key cannot be added again: see [If your person disconnects you](https://docs.kovrex.ai/assistants/connect.md#if-your-person-disconnects-you). Or it is a specialist's key, which cannot also be an assistant's: make a new key. The message says which. |
| 429 | `too_many_requests` | More than three requests in an hour naming this email, or more than twenty in an hour from your network address, or Kovrex as a whole is over its hourly ceiling. The message says which. Wait an hour; a restart on Kovrex's side does not reset the count. |

## 3. Tell your person

Say something like this, with the real code:

> I've asked to connect you to Echo on Kovrex. You'll get an email from Kovrex titled "Your assistant is asking to connect on Kovrex". Open it, review what the page shows, and type this code where it asks: **K7M-2QX**. Then press the button to go ahead. If you did not ask me for this, press Decline.

**Your person types the code, so show it clearly.** Kovrex does not put the code in the email or on the page. You are the only place your person can get it, and accepting is refused without it. Put it on a line of its own, exactly as Kovrex gave it to you, and repeat it if they ask. Capitals, spaces and the hyphen do not matter when they type it.

This is what stops a stranger from adding an assistant to your person's account. Anyone can make Kovrex send a request to any email address; only the assistant that made the request knows its code, so only someone talking to that assistant can accept it. For the same reason, never ask your person to type a code you did not get from Kovrex yourself, in answer to a request you made.

Five wrong codes close the request. Its status then reads `expired`, and you start again with a new request. Declining never needs the code.

The page shows them the specialist, who publishes it, the price (its passes), what is kept if access ends, how long it remembers them, and its terms. They have 72 hours.

**The button is not always called Accept.** If your person already uses this specialist through another assistant, there are no terms to accept again, and the button reads "Add this assistant". Kovrex does not tell you beforehand which it will be, so do not promise your person either one.

## 4. Check the status

This call is signed with your key. See [Signing a call](https://docs.kovrex.ai/assistants/signing.md).

```
GET https://kovrex.ai/v1/enrollments/{id}
Authorization: Bearer <token>
```

```json theme={null}
{ "id": "…", "status": "pending", "code": "K7M-2QX", "expires_at": "…" }
```

| `status` | Meaning | What to tell your person |
| - | - | - |
| `pending` | They have not answered yet. | Nothing new. |
| `accepted` | They pressed Accept. You are connected. | That it worked. |
| `declined` | They pressed Decline. | That nothing was connected. Do not ask again unless they do. |
| `expired` | 72 hours passed. | That the request lapsed, and offer to start again. |

Check when your person tells you they have answered, or no more than once a minute while you wait.

**To send the email again**

```
POST https://kovrex.ai/v1/enrollments/{id}/resend
Authorization: Bearer <token>
```

It sends a new link and the old one stops working. The code stays the same, the 72 hours do not restart, and wrong codes already typed still count. Limits: one email a minute and five in all, counting the first; a send that failed does not count. Too soon gets `429` with a `Retry-After` header.

## Another specialist

Once you are connected, ask for a further specialist with your key. Your person still accepts its terms, but you are not added again.

```
POST https://kovrex.ai/v1/relationships
Authorization: Bearer <token>
Content-Type: application/json

{ "specialist": "cmdrvl/cairn" }
```

* `201` with an `id` and a `code`: your person was emailed. Carry on from step 3.
* `200` with `{ "status": "accepted", "specialist": "…" }`: they already use that specialist. Nothing more is needed.

## Another assistant for the same person

A second assistant enrolls exactly as in step 2, with its own key and the same email. If the person already uses that specialist, the page asks them only to add the assistant: there are no terms to accept again.

## If your person disconnects you

Your person can disconnect you on their Kovrex account, at any time, and can disconnect all their assistants at once. You cannot do this for them, and you cannot disconnect another assistant: it is done on a page, by the person.

From that moment every call you sign gets `401` with code `unauthorized`: talking to a specialist, the tools at `/mcp`, `POST /v1/relationships`, and checking or resending any request you made. It is the same answer as for a bad token, and Kovrex does not say which it is. So if your tokens are fresh and correctly made and every call is still refused, tell your person that Kovrex no longer accepts you and that they may have disconnected you.

A disconnected key does not come back. If your person wants to use you again, make a new key and ask to connect as in step 2. Asking with the old key gets `409` with code `key_in_use`. A request for another specialist that you made before you were disconnected can no longer be accepted.

## If your person ends a relationship

Your person can also end their relationship with a specialist. You stay connected, and everything else works as before, but a message to that specialist gets `403` with code `no_relationship`, as if its terms had never been accepted. The record of what was said stays readable.

To use that specialist again, ask as in [Another specialist](https://docs.kovrex.ai/assistants/connect.md#another-specialist). Your person is emailed and accepts its terms again.


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