Agent sign-in

Connect a coding agent through human-approved MCP onboarding, verified account creation and checkout, or the existing auth.md sign-in flow.

Coding agents can request their own Kourier API key without you copying a key from the dashboard. The MCP onboarding flow combines verified account sign-in or creation, plan confirmation, checkout when needed, and explicit agent approval. The existing auth.md service_auth flow remains available for account-based sign-in.

The machine-readable instructions agents follow are at kourier.sh/auth.md.

MCP onboarding: account, checkout, and agent access

Connect your tool to the public MCP endpoint at https://kourier.sh/mcp. No Kourier API key is needed to start onboarding.

  1. The agent calls create_checkout_link with plan (starter or pro), client_name, and an optional harness (oh-my-pi, claude-code, codex, or openai-compatible).
  2. It shows you the returned onboarding_url and six-digit user_code. It must keep onboarding_token private; never include that token in a link, public message, or log.
  3. Open the link. Sign in with Google/GitHub or an email code. Email-code sign-in creates an account only after verifying the code; existing accounts are reused. Account creation follows the site's signup policy.
  4. Review the agent name, requested plan, and recurring price: Starter $20 USD/month or Pro $50 USD/month, with any applicable taxes shown at checkout. Enter the code from your agent and explicitly approve both agent access and the subscription if one is needed. Signing in alone grants neither.
  5. If you need a subscription, complete payment yourself in Dodo's hosted checkout. The agent does not collect card details or complete payment for you. Returning from checkout is not proof of payment: access waits for the signed subscription webhook and entitlement activation.
  6. Return to the agent. It polls get_onboarding_status every five seconds, then calls complete_onboarding only when the status is ready. That call delivers a dedicated API key once, plus the API base URL, model, and setup instructions for the selected harness. Configure the tool only with your approval.

If your account already has eligible access, onboarding uses your current entitlement without another charge or an automatic plan upgrade. Change your plan separately in Billing if needed. The key is never displayed on the connection page; manage or revoke it in Dashboard → API Keys.

Only approve a request you just started in a tool you trust. The displayed agent name is supplied by the agent, not verified by Kourier. Choose Deny if you did not start the request.

MCP status and one-time delivery

An onboarding link and its approval code expire after one hour. Five wrong approval codes cancel the request. Creation, polling, and key exchange are rate-limited.

  • awaiting_approval: waiting for verified browser sign-in and explicit approval.
  • awaiting_payment: approval exists, but the required payment is not confirmed.
  • activating: payment or current account access is still being verified. Do not pay again.
  • ready: call complete_onboarding once.
  • issuing: key delivery is in progress; check status rather than repeating completion.
  • issued, denied, or expired: stop polling and completion. Never repeat an issued exchange.

Keep the returned access_token securely as your API key (for example, as KOURIER_API_KEY). It shares your existing account's limits. If completion loses its response, check status: an issued key cannot be retrieved again. Revoke the dedicated key in the dashboard and start a new human-approved request if necessary.

Tool builders can also use the same JSON HTTP endpoints directly:

StepEndpoint
CreatePOST https://app.kourier.sh/agent/onboarding with { "plan": "starter", "client_name": "My tool", "harness": "codex" }
PollPOST https://app.kourier.sh/agent/onboarding/status with { "onboarding_token": "…" }
Complete oncePOST https://app.kourier.sh/agent/onboarding/token with { "onboarding_token": "…" }

No agent-supplied email, account ID, checkout URL, or payment method is accepted. The approving browser account owns the request, and checkout metadata binds verified payments to that account.

Submit feedback and error reports

Once you have a key, use submit_feedback through MCP or POST https://kourier.sh/api/feedback with the same bearer credential. See Feedback and error reports for examples, fields, privacy guidance and submission limits.

Existing-account auth.md approval

The service_auth flow remains separate from MCP onboarding: the agent asks for a key using your email, shows you a six-digit code, and you approve it in your browser. Its renewable ten-minute code is not the one-hour MCP approval code.

What you'll see

  1. 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?... and 123456.
  2. Open the link and sign in with the same email the agent used.
  3. Check the page: the agent's name, when the request was made, and the country it came from.
  4. Type the code and choose Approve. The agent receives its key a few seconds later.

You need an API-access plan. Choose Starter or Pro if you do not 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.

auth.md 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.

StepEndpoint
RegisterPOST https://app.kourier.sh/agent/identity with { "type": "service_auth", "login_hint": "<email>", "client_name": "<your tool>" }
New codePOST https://app.kourier.sh/agent/identity/claim with { "claim_token", "email" }
Poll for the keyPOST https://app.kourier.sh/oauth2/token with grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=…
RevokePOST 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:

  1. Generate a PKCE code_verifier and its S256 code_challenge, and listen on a loopback port.
  2. 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.
  3. The user signs in and approves. The browser returns to your redirect_uri with code, state, and iss.
  4. Exchange it: POST https://app.kourier.sh/oauth2/token with grant_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>.