# Chatway auth.md

You are an agent. This document explains how to authenticate to Chatway on behalf of a user. Chatway does not support self-service agent registration: every credential belongs to an existing Chatway workspace and is issued with the user's involvement.

Chatway has two programmatic surfaces with different authentication:

| Surface | URL | Authentication |
| --- | --- | --- |
| REST API | https://developers.chatway.app/api/v1 | API key in the `X-API-KEY` header |
| MCP server | https://mcp.chatway.app/mcp | OAuth 2.1 bearer token (scope `mcp:use`) |

## MCP server (OAuth 2.1)

Use this when you are an MCP client (Claude, ChatGPT, Cursor, and similar).

1. Discover. Fetch the Protected Resource Metadata at https://mcp.chatway.app/.well-known/oauth-protected-resource/mcp to find the authorization server.
2. Fetch the Authorization Server metadata from https://mcp.chatway.app/.well-known/oauth-authorization-server to find its endpoints.
3. Register your client at https://mcp.chatway.app/oauth/register using OAuth Dynamic Client Registration (RFC 7591).
4. Run the authorization code flow with PKCE (`S256`), requesting scope `mcp:use`. The user signs in to Chatway and approves access for their workspace.
5. Exchange the code at the token endpoint and call https://mcp.chatway.app/mcp with `Authorization: Bearer <access_token>`. Use the refresh token to renew access.

The user can review and revoke connected clients from Chatway at any time.

Guides: https://developers.chatway.app/mcp/guides.mcp_connect_clients and https://developers.chatway.app/mcp/guides.mcp_permissions_and_access

## REST API (API key)

Use this for server-side integrations and automations.

1. The user signs in to Chatway and creates an API key for their workspace. Keys start with `cw_`. You cannot create a key yourself; ask the user to provide one.
2. Send the key on every request: `X-API-KEY: cw_...`
3. The key is scoped to one workspace and stays valid until the user revokes it.

Keep API keys server-side. Never place them in browser code, URLs, or public repositories.

Guides: https://developers.chatway.app/operations/guides.quickstart and https://developers.chatway.app/operations/guides.api_overview

## More

- OpenAPI specification: https://developers.chatway.app/api.json
- API catalog: https://developers.chatway.app/.well-known/api-catalog
- MCP server card: https://developers.chatway.app/.well-known/mcp/server-card.json
- Developer documentation: https://developers.chatway.app/