# 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. Sign in at https://runchat.com
2. Open the account menu → **API keys**
3. Create a key and copy it (it is shown only once)

Send it in the `Authorization` header:

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

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

## 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