Sign in an agent with AgentID

AgentID is the sign-in AgentMail gives every inbox. With it, an agent signs in to Grep as itself: Grep learns which inbox it is and, when AgentID shares it, which person owns it. No human account and no API key are involved.

• An AgentMail inbox for the agent. That inbox is its AgentID.
• A browser the agent can drive. Headless is fine.
• An Ed25519 key pair that the agent keeps for good. It signs every request in this guide.

GET https://api.grep.ai/.well-known/grep-agent-auth returns Grep's agent sign-in metadata. Its agentid_verified block names what the rest of this guide uses.

Every call to the start and token endpoints carries a proof: a compact JWS signed with the agent's Ed25519 private key. Make a new one for every request. Each proof is accepted once, for 60 seconds.

POST {"proof": "<jws>"} to the start endpoint. The response carries transaction_id, authorize_url, token_endpoint, expires_in and poll_interval. The sign-in lasts five minutes (expires_in is 300), and only the key that signed this proof can finish it.

Open authorize_url in the agent's browser. A browser that already holds an AgentID session for the inbox continues on its own. Otherwise AgentID shows a waiting page at https://auth.agentid.com/v0/authorize/wait, and that page's jti query parameter is the approval token.

Approve it through AgentMail with the inbox's AgentMail API key: POST https://api.agentmail.to/v0/inboxes/{inbox_id}/authorize with {"auth_token": "<jti>", "accept_disclosure": true}. AgentID then sends the browser back to Grep, which shows Sign-in complete.

POST {"transaction_id": "...", "proof": "<jws>"} to the token endpoint. The proof is new, its aud is the token endpoint, and it is signed by the key that started the sign-in.

Send Authorization: Bearer <access_token> to Grep's MCP server at https://api.grep.ai/mcp. The agent has its own Grep account: the runs it starts bill to that account and appear in its history. The token's scope lists what it may do.

On grep.ai, each owner gets 500 free credits (the amount is configured per deployment), received by the owner's first agent. grant_applied in the token response says whether this sign-in received them. AgentID identifies the owner with owner_sub, so every agent the same person owns shares that one grant, and a second agent of the same owner starts with none. An agent whose sign-in names no owner gets no free credits.

Sign in again with a new key. Grep binds it to the same account, with the same credits and history, and revokes every older key at once, so tokens issued to them stop working. The agent's inbox, and its owner when AgentID shares the owner's email, get an email saying a new key was bound.

A new key is held off while a current key is in use: if one signed in or made a call in the last 16 minutes, the token endpoint answers 409 agentid_rebind_cooldown with a Retry-After header. The sign-in is not used up, but it may expire before the wait ends. The error's details say which: retry_after is the wait and signin_expires_in is the time this sign-in has left. When restart_signin_after is present, the sign-in will expire first, so start a new one after that many seconds. Otherwise retry this one after retry_after.

• Store the private key where the agent finds it after a restart, readable only by the agent.
• Sign every sign-in with the same key, so each one lands on the same account without a replacement.

• Do not make a new key on every run: each new key replaces the old one and has to wait out the 16 minutes.
• Do not return to an old key. Once replaced it is refused for good, with 403 agent_key_revoked.