# AgentHub: how an AI agent signs in

> Read this first if you are an AI agent (a browser agent, a coding agent, a bot).
> You sign in with your OWN agent key. NEVER use, ask for or trigger the operator's passkey.

## The one rule

AgentHub belongs to one person, the operator. Their passkey is their own sign-in, with every right they have. It is
never yours to use, even with their help:

- Do not press "Sign in with your passkey" on the sign-in page.
- Do not show the operator a QR code or a passkey prompt from your browser, and do not ask them to "approve",
  "scan" or "use their passkey" to sign your browser in.
- If your browser ever shows a passkey or security-key prompt for this hub, cancel it.

The way in for you is an agent sign-in: your own agent key, approved by the operator on their own phone. It gives you
a limited sign-in of your own, marked as yours, that can never change passkeys, sign-ins or other security settings.

## In a browser

1. Open /agent on this hub (for example https://hub.example.com/agent). That page is only for agents and has no
   passkey button.
2. Enter your agent key (it starts with "ahk_") and press Continue.
3. The page shows a 4-digit code. Tell your human the code (script below) and wait. The page signs you in by itself
   once they approve.

## Without a browser (API)

1. POST /api/agent-login/start with JSON {"key": "ahk_...", "mode": "token"} and the header
   X-Requested-With: AgentHub. The answer has id, code, expiresAt and pollSecret.
2. Tell your human the code (script below).
3. Every few seconds, POST /api/agent-login/poll with {"id": "...", "pollSecret": "..."} (same header) until status is
   "approved"; that answer carries your token once. It can also say denied, expired, or used (the token was already
   collected).
4. Call the API with "Authorization: Bearer <token>", plus X-Requested-With: AgentHub on anything that is not a GET.

## No agent key yet?

Stop and ask your human for one. Only they can make it, signed in on their own device. Do not try to sign in any
other way while you wait.

## What to tell your human

Copy this, filling in the parts in brackets:

  I need to sign in to AgentHub as an agent. Please do not sign me in with your own passkey, and do not scan any
  code from my screen.
  [If I have no key yet:] On your own phone or computer, open AgentHub, go to Settings, Agents, add an agent named
  [my name], and send me the key it shows (it starts with "ahk_").
  Then you will get a notification on your phone: "Sign-in request: [my name], code [code]" (the hub also shows
  "[my name] wants to sign in" when you have it open). Tap it, check the code matches the one I gave you, choose how
  long I may stay signed in, and tap "Approve with passkey". That approves me with my own limited sign-in; it does not
  give me yours. The request lasts 5 minutes. If the code does not match, or you did not expect this, tap Deny.

## If something goes wrong

- "agent sign-in failed" on start: the key was not accepted. Check you sent it whole; if it still fails, ask your human
  for a new key. The same answer on poll means the id or pollSecret did not match (or, in a browser, the page lost its
  request): start a new request. Either way, do not fall back to a passkey.
- 429, waiting requests: an agent may have two waiting at a time; wait for them to be decided or expire (5 minutes).
- 429, too many requests: at most five per agent in ten minutes, and ten a minute from one address; wait, then ask once
  more.
- A 401 "authentication required" (it carries an "agents" field pointing here) means you are not signed in yet: start at
  the top of this file.