# Auth.md — Authenticating agents with the Open (OpenCX) API

This document tells AI agents and automated clients how to authenticate with
Open's REST API. Open uses **bearer-token authentication with API keys** — there
is no interactive OAuth flow.

## Resource

- **API base URL:** `https://api.open.cx`
- **OpenAPI specification:** `https://api.open.cx/api-json`
- **API reference:** https://docs.open.cx/api-reference/
- **Protected-resource metadata:** `/.well-known/oauth-protected-resource`

## How to get a credential

API keys are issued from the Open dashboard — there is no programmatic
registration endpoint.

1. Sign in at https://platform.open.cx
2. Go to **Settings → API Keys** (https://platform.open.cx/settings/access)
3. Create a key, scoped as needed. Keys can be rotated and revoked freely.

## How to authenticate a request

Send the API key as a bearer token in the `Authorization` header on every
request:

```http
GET /v1/sessions HTTP/1.1
Host: api.open.cx
Authorization: Bearer YOUR_API_KEY
```

- **Scheme:** HTTP bearer
- **Token format:** JWT
- **Transport:** HTTPS only

## Error handling

- `401 Unauthorized` — missing or invalid token. Re-check the key and header.
- `403 Forbidden` — the token is valid but lacks the required scope.

Rotate keys regularly and handle the standard `401`/`403` responses.
Full details: https://docs.open.cx/api-reference/authentication

## MCP server

Open also ships an MCP server for use from Claude Desktop, Cursor, VS Code,
Windsurf, and Zed. It runs locally over stdio and authenticates with the same
API key:

```bash
npx -y @opencx/mcp   # set OPENCX_API_KEY in the environment
```

- Setup: https://docs.open.cx/mcp/install
- Server card: `/.well-known/mcp/server-card.json`