AUTHENTICATION
OAuth 2.1 with PKCE
COSMOS follows the MCP authorization spec. Clients discover everything from the metadata below; people sign in with their Reach account.
Flow
- Call
https://cosmic-mcp.app/mcpwithout a token: the 401 carriesWWW-Authenticatewith the protected resource metadata URL (RFC 9728). - Read the authorization server metadata (RFC 8414) and register if you have no client id (RFC 7591).
- Send the person to
/oauth/authorizewith PKCE S256 (plain is refused),stateandresource=https://cosmic-mcp.app/mcp(RFC 8707). - They sign in with Reach and tick the scopes they allow. You get a code at your redirect URI.
- Exchange it at
/oauth/token. Refresh tokens rotate on every use; replaying an old one revokes the whole chain.
Metadata URLs
https://cosmic-mcp.app/.well-known/oauth-protected-resourcehttps://cosmic-mcp.app/.well-known/oauth-authorization-serverClient registration
Dynamic client registration is open at /oauth/register.
New clients wait for a COSMOS administrator to approve them; until then sign-in shows that the client is pending.
Public clients use token_endpoint_auth_method: none with PKCE. Redirect URIs must be https, or http on a loopback address for native apps.
Token lifetimes
- Access token: 1 hours (opaque, revocable at once)
- Refresh token: 30 days, rotated on every use
Scopes
| Scope | Leg | What it allows |
|---|---|---|
bridge:connect | browser | Let your local bridge connect to COSMOS |
browser:drive High risk, off by default | browser | Drive tabs in the TheOne Agent group of your own browser |
browser:evaluate High risk, off by default | browser | Run JavaScript in pages you enabled it for |
cosmos:admin High risk, off by default | cosmos | Administer COSMOS: clients, legs, policies |
cosmos:jobs | cosmos | See and cancel your own long-running jobs |
cosmos:service High risk, off by default | cosmos | Internal service: act for a Reach workspace the caller already authorized (client_credentials only) |
plugins:admin High risk, off by default | cosmos | Publish and distribute plugins |
plugins:read | cosmos | List the plugin catalogue |
icarus:generate | icarus | Generate concept briefs with MERLIN (uses compute) |
icarus:publish High risk, off by default | icarus | Schedule approved posts (each post needs your click) |
icarus:read | icarus | Read your client's persona, trends, predictions and reports |
icarus:write | icarus | Edit your client's persona card |
models:generate High risk, off by default | models | Generate text, images, video and voice with your workspace's own AI keys (paid calls need your OK in Reach) |
models:read | models | See the AI providers and estimate the cost of a generation |
veritas:approve High risk, off by default | veritas | Approve or deny agent actions that wait for a person |
veritas:contain High risk, off by default | veritas | Suspend or release your organization's agents |
veritas:read | veritas | Read your organization's agent passports and receipt sessions |
veritas:verify | veritas | Check receipts, passports and artifact credentials against the trust list and the log |