Docs · Agents

Sign up from an agent

An AI agent can sign up for froog without a human pasting an API key. froog implements auth.md, the WorkOS agent registration protocol, like boat. The contract is a machine-readable file at froogcorp.com/auth.md. Give the agent this instruction:

Follow https://froogcorp.com/auth.md and sign me up for froog sandboxes.
  1. It finds the endpoints: a 401 from the API carries WWW-Authenticate: Bearer resource_metadata="https://api.froogcorp.com/.well-known/oauth-protected-resource/v1", and /.well-known/oauth-authorization-server has the agent_auth block (the same document as for MCP clients when OAuth for MCP is on: its token endpoint takes both flows' grants).
  2. It registers: POST /v1/agent/identity with {"type": "anonymous"}, or {"type": "service_auth", "login_hint": "you@example.com"} when it knows your email. While froog is invite-only, an address without an account answers 403 invite_only with the link to request access; an anonymous agent can still register, but only someone already invited can claim it.
  3. It sends you a link and a 6-digit code. You open the link, sign in (any method), and type the code. A registration bound to an email needs an account with that address (403 wrong_account otherwise).
  4. It polls POST /v1/oauth2/token and gets an API key on your account. Then, if the account has no card yet, it opens the add-a-card page (POST /v1/billing/card returns Stripe Checkout; you enter the card, and then a lite sandbox runs free).
MethodTokenWhat the agent can do
AnonymousAt once, by exchanging its identity assertionOnly account.read (GET /v1/account, /v1/limits). Anything else answers 403 claim_required until you claim it.
Email (service_auth)After you sign in and type the codeIt must know your email.

A claimed agent's key has the actions to create and run sandboxes, snapshots and files, read the environment, and billing.trial: it can read billing and open the add-a-card page (you complete Stripe Checkout). It can't pay into the wallet, change auto top-up or the spending cap, or create API keys (403 api_key_action_forbidden). The agent can exchange its identity assertion for a new key, which revokes the previous one, only while its current key is live. Revoke the key any time on the API keys page, with POST /v1/oauth2/revoke or POST /oauth/revoke: that ends the agent's registration, so its assertion gets no new key (invalid_grant) and it must register and be claimed again. The same goes when the key expires after 90 days. froog doesn't accept identity assertions from agent providers (ID-JAG): sending one answers issuer_not_enabled. Claim tokens last 24 hours, codes 10 minutes and 5 tries, and each network (an IPv4 address or an IPv6 /64) can register 10 agents an hour.