# auth.md

Runchat supports two ways for agents and API clients to authenticate:
**OAuth 2.1** (recommended — used by the MCP server) and **Bearer API keys**.

## OAuth 2.1 (MCP server)

Connect an MCP client to `https://runchat.com/api/mcp` (Streamable HTTP) and
it will be walked through the OAuth flow automatically:

1. An unauthenticated request returns `401` with a `WWW-Authenticate` header
   pointing at https://runchat.com/.well-known/oauth-protected-resource
2. That document lists the authorization server. Its metadata (also mirrored at
   https://runchat.com/.well-known/oauth-authorization-server) includes the
   registration endpoint — dynamic client registration (RFC 7591) is open, so
   no pre-registration is needed. PKCE is required.
3. The user signs in and approves access on the consent page, and the client
   receives access + refresh tokens.

Send the access token on every request:

```
Authorization: Bearer {access_token}
```

The MCP server card is published at
https://runchat.com/.well-known/mcp/server-card.json

## Bearer API keys

For server-to-server use without a browser flow:

1. Open https://runchat.com/dashboard?newkey=true (sign in if asked) — this
   creates a new key and shows it in the account menu. Or open the account
   menu → **Get Runchat API Key** and create one there.
2. Copy the key

Send it in the `Authorization` header:

```
Authorization: Bearer {api_key}
```

API keys work on every endpoint below, including the MCP server.

## Command-line client

`@runchat/cli` wraps the MCP server for shell and agent use. Sign in with the
browser — no key handling needed:

```
npx -y @runchat/cli status     # exit 0 = signed in, exit 3 = not signed in
npx -y @runchat/cli login      # opens the browser (OAuth 2.1 + PKCE); waits up to 5 min
```

`login` blocks until the user approves in the browser, so agents should run
it in the background and tell the user a sign-in page has opened (the command
also prints the URL). The session is stored locally and refreshes itself.

For CI or headless machines, use an API key instead: `RUNCHAT_API_KEY`, the
`--api-key` flag, or `npx @runchat/cli login --paste` (opens the new-key page,
then reads the key). Never ask a user to paste a key into an agent chat.

## Endpoints

- **MCP** — `POST https://runchat.com/api/mcp` (full canvas + workflow tools over MCP)
- **Execution** — `POST https://runchat.com/api/v1/{runchat_id}` (run a workflow)
- **Schema** — `GET https://runchat.com/api/v1/{runchat_id}/schema` (inputs/outputs)
- **Canvas** — `POST https://runchat.com/api/v1/{runchat_id}/canvas` (read/edit the graph)

## Discovery

- MCP server card — https://runchat.com/.well-known/mcp/server-card.json
- Protected resource — https://runchat.com/.well-known/oauth-protected-resource
- Authorization server — https://runchat.com/.well-known/oauth-authorization-server
- Skills index — https://runchat.com/.well-known/agent-skills/index.json
- API catalog — https://runchat.com/.well-known/api-catalog
- OpenAPI — https://docs.runchat.com/api-reference/openapi.json
- Canvas skill — https://runchat.com/api/skills/canvas
- Index — https://runchat.com/llms.txt
