Agent sign-in
Let a coding agent get its own Kourier API key for your account through the auth.md flow, with a code you approve in the browser.
Coding agents can request a Kourier API key on your behalf instead of you copying one from the dashboard. Kourier implements the auth.md service_auth flow: the agent asks for a key using your email, shows you a six-digit code, and you approve it in your browser.
The machine-readable instructions agents follow are at kourier.sh/auth.md.
What you'll see
- The agent tells you it wants to create a Kourier API key and shows a link and a code, for example
https://app.kourier.sh/claim?...and123456. - Open the link and sign in with the same email the agent used.
- Check the page: the agent's name, when the request was made, and the country it came from.
- Type the code and choose Approve. The agent receives its key a few seconds later.
You need a Pro, Max, or Omega plan. If you don't have one, the page asks you to choose a plan first.
Only approve a request you just started yourself. If the page says the request came from a different country than you're in, and you aren't using a VPN or a remote machine, choose Deny. Someone may be trying to get a key for your account.
The key
- It is a normal Kourier API key, labelled Agent: <name> under Dashboard → API Keys.
- It shares your plan's concurrency with your other keys; extra keys never add capacity.
- An account can hold up to 5 active keys. Revoke one to make room.
- It does not expire. Revoke it in the dashboard at any time, or the agent can revoke it itself.
Limits
- A code is valid for 10 minutes; the whole request for 1 hour. The agent can ask for a new code.
- Five wrong codes cancel the request.
- Registrations are rate-limited per email and per network address, so a flood of requests is refused.
For agent and tool builders
Discovery starts from any API call without a key: the 401 includes
WWW-Authenticate: Bearer resource_metadata="https://api.kourier.sh/.well-known/oauth-protected-resource"which names the authorization server https://app.kourier.sh. Its metadata, including the agent_auth block, is at /.well-known/oauth-authorization-server.
| Step | Endpoint |
|---|---|
| Register | POST https://app.kourier.sh/agent/identity with { "type": "service_auth", "login_hint": "<email>", "client_name": "<your tool>" } |
| New code | POST https://app.kourier.sh/agent/identity/claim with { "claim_token", "email" } |
| Poll for the key | POST https://app.kourier.sh/oauth2/token with grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=… |
| Revoke | POST https://app.kourier.sh/oauth2/revoke with token=… |
The token response's access_token is the API key. Use it as described in Get Started, or for Oh My Pi in the Oh My Pi guide.
Browser sign-in for CLIs (OAuth 2.0 + PKCE)
Command-line tools can use the standard authorization code flow instead, like gh auth login:
- Generate a PKCE
code_verifierand its S256code_challenge, and listen on a loopback port. - Open
https://app.kourier.sh/oauth2/authorize?response_type=code&client_id=<your tool>&redirect_uri=http://127.0.0.1:<port>/callback&code_challenge=<challenge>&code_challenge_method=S256&state=<random>in the user's browser. - The user signs in and approves. The browser returns to your
redirect_uriwithcode,state, andiss. - Exchange it:
POST https://app.kourier.sh/oauth2/tokenwithgrant_type=authorization_code&code=…&client_id=…&redirect_uri=…&code_verifier=….
Only loopback redirect URIs (127.0.0.1, [::1], localhost) are accepted, PKCE S256 is required, and a code is valid once, for 5 minutes. The access_token is a Kourier API key labelled OAuth: <client_id>.