Skip to main content

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

This call is not signed.
What comes back 201 Created:
  • 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": "…" } }.

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.
Check when your person tells you they have answered, or no more than once a minute while you wait. To send the email again
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.
  • 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. Your person is emailed and accepts its terms again.