# auth.md

Kody is Your agents' cloud: an OAuth-protected MCP cloud for individuals and teams.
Agents connect at `https://kody.nafigroup.app/mcp` from an existing MCP host. People complete
sign-in and consent in the browser; do not ask anyone to paste credentials
or tokens into chat.

## Add the MCP server

1. Point the host at `https://kody.nafigroup.app/mcp`.
2. Complete the OAuth flow the host opens. Sign in to Kody if needed,
   then approve access.
   No account yet? The person can pick Try it out on the sign-in screen and claim the account later by telling their agent.
3. The account email must be verified before authorize can finish. If
   authorize asks to verify, keep that tab open, finish verification
   from the email link or `/pending-verification`, then continue.
4. After the connection works, call `search` before `execute`.

Client-specific setup (Cursor, ChatGPT, Claude Desktop, Claude Code,
Codex, Copilot, Grok, OpenCode, OpenClaw, Hermes Agent, Muse) lives on
`/onboarding`. A no-account capability tour is at `https://kody.nafigroup.app/docs/what-is-kody.md`;
the full docs index is `https://kody.nafigroup.app/llms.txt`.

## OAuth

- Authorization server: `https://kody.nafigroup.app/.well-known/oauth-authorization-server`
- Protected resource: `https://kody.nafigroup.app/.well-known/oauth-protected-resource/mcp`
- Resource: `https://kody.nafigroup.app/mcp`
- Scopes: `openid`, `profile`, `email`
- Dynamic client registration: `https://kody.nafigroup.app/oauth/register`
- Client ID Metadata Documents (CIMD) are supported.

## Register a person from a shell (auth.md `service_auth`)

Agents without an MCP host can register the person they act for. The
`agent_auth` block in `https://kody.nafigroup.app/.well-known/oauth-authorization-server` is authoritative.

1. `POST https://kody.nafigroup.app/agent/identity` with
   `Content-Type: application/json` and
   `{"type":"service_auth","login_hint":"<their email>"}`. Optional
   `lifetime`: `"short"` or `"long"` (default `long`). Keep `claim_token`
   in memory only.
2. Show the person `claim.verification_uri` and `claim.user_code` in one
   message. They sign in or sign up (choosing their own username), verify
   their email, and type the code on that page. Kody never emails it.
3. Poll `POST https://kody.nafigroup.app/oauth/token` with
   `grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=<claim_token>`
   every `interval` seconds. `authorization_pending`: wait. `slow_down`:
   add 5 seconds. `expired_token`: get a fresh code with
   `POST https://kody.nafigroup.app/agent/identity/claim` (JSON)
   `{"claim_token":"<claim_token>","email":"<their email>"}`, then show
   the person `claim_attempt.verification_uri` and
   `claim_attempt.user_code`. After `claim_expired`, register again.
4. Success returns a `kody_at_` `access_token` for the Open API and
   `@kodycodes/cli` (`KODY_API_TOKEN`). It does not work on `/mcp`.
   There is no refresh token; register again when it expires.

`anonymous` and `identity_assertion` registration are not enabled.