Signing in
How accounts, organizations, sign-in codes, OAuth grants, sessions and API tokens work — and why you never handle a credential.
There is no password on agenthost, and nothing to paste into a chat window. Signing up, signing in and connecting a client are all the same act: your MCP client sends you to agenthost in your browser, you prove you own an email address, and the client gets a token you never see.
The short version
Your client asks agenthost for access
The first call fails as unauthenticated, and agenthost tells the client where to authorize. Clients register themselves automatically — there's no console visit and no client secret.
You sign in with your email
A six-digit code arrives by email, valid once and for about ten minutes. Type it back. If the address is new, this same step creates your account: you name your organization and accept the terms.
You approve the client by name
You see which client is asking. Approve it, and it exchanges a one-time code for tokens.
Your browser stays signed in for 30 days, so authorizing the next client is a single click.
Accounts and organizations
An organization — sometimes called a customer in tool output — is the account everything belongs to. A user is a person, identified by their email address, who can belong to as many organizations as they've been invited to, holding a different role in each.
That join is a membership, and it's the only thing that grants access. It's re-checked on every request, so removing someone locks them out at once and leaves their other organizations untouched.
A credential is bound to exactly one organization. Every OAuth grant, API token and browser
session is scoped to one, and every tool call reads and writes only its data. To work on another
organization, connect a client again and pick it during sign-in. There's no tool that switches
mid-session; whoami tells you which others you belong to.
Roles
owner, admin and member. Today only inviting users is role-gated — owners and admins can do it,
members can't. Everything else, including deleting apps and projects, is available to any member. See
Work with teammates.
Tokens and lifetimes
| Credential | Lives | Notes |
|---|---|---|
| Access token | 1 hour | Your client refreshes it silently |
| Refresh token | 60 days, renewed on use | Rotates on every use; revoking either half drops the whole grant |
| Browser session | 30 days | Why the second client is one click |
| Sign-in code | ~10 minutes, one use | Five wrong guesses burns it |
| API token | Until revoked | For clients that can't open a browser — see Deploy from CI |
| App visitor session | 7 days | For invite-only apps; the allowlist is still checked every request |
Only hashes are stored — SHA-256 with a server-side pepper — for API tokens, OAuth tokens, sign-in codes and sessions alike. Nobody can read a credential back out of agenthost, including us.
What this means in practice
- Your agent never sees your credentials. The client holds a token; you hold nothing.
- Nothing to rotate on a schedule. OAuth grants refresh themselves. Only API tokens are long-lived, and those are yours to rotate.
- Revocation is immediate. Disconnecting a client, revoking a token or removing a membership takes effect on the next request, not at the next sign-in.
Rate limits
The endpoints that need no credential are rate limited — most sharply, sign-in codes per email address. If you've asked for several codes in a row, wait a few minutes before trying again.
For the protocol-minded
agenthost is its own OAuth 2.1 authorization server, as the MCP authorization spec describes: RFC 9728 protected-resource metadata, RFC 8414 authorization-server metadata, RFC 7591 dynamic client registration, mandatory PKCE (S256), and RFC 7009 revocation. Any spec-compliant MCP client connects without configuration beyond the URL.