Every request to a CharmIQ MCP server carries a bearer token. The token is issued by CharmIQ's OAuth 2.1 server, scoped to a single Organization, and tied to the set of permissions the user granted. The whole flow is standards-compliant — any MCP client that supports discovery will configure itself automatically.

This page is the developer reference. If you're connecting an off-the-shelf client (Claude Code, VS Code, Zapier), use 

CharmIQ implements RFC 8414 (Authorization Server Metadata) and RFC 9728 (Protected Resource Metadata). Point your client at the well-known URLs and it learns the rest.

. The token issued from this server works against every sub-server (

, etc.) — you do not authorize per server.

. PKCE is mandatory for every authorization request — 

The standard sequence for a public client:

Decode the JWT locally if you need to know which Organization a token is bound to before calling an MCP endpoint.

 parameter, every scope that client is allowed to have is granted by default. In practice, scope-down by request when you only need read access.

Refresh-token rotation is real: a refresh call returns a new refresh token, and the old one stops working. If your application loses a refresh token (network blip, crashed write), the user has to go through consent again.

For a backend integration that runs without a user in the loop, an Organization Owner can create a scoped OAuth client with a client secret directly in CharmIQ. These confidential clients:

This is the right path when you don't want a human consent step every time. The setup lives in CharmIQ's authorization settings — 

Once you have a token, every MCP call is the same: an HTTP 

curl -X POST https://api.charmiq.ai/mcp/vfs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_dir",
      "arguments": { "uri": "root" }
    }
  }'

A standard MCP SDK does all of this for you — you call 

 and the transport layer handles JSON-RPC framing. The flow above is what to expect if you're writing the transport yourself.

Users can revoke any inbound connection from CharmIQ's authorization settings. Organization Owners can also revoke a client across the entire Organization in one action. A revoked client's tokens stop working immediately — the next API call returns a 401.

CharmIQ surfaces every active inbound connection in the user's settings: the client's name, when it was authorized, the granted scopes, and the last time it was used. Build your application to fail gracefully on the next 401 and re-enter the OAuth flow.

 — The surface map: what each server does and where to look next.

 — End-user setup for the off-the-shelf clients.

 — The same OAuth infrastructure, used the other direction: a CharmIQ Application authenticating outward.

How OAuth 2.1 works across CharmIQ's MCP servers — discovery endpoints, token flow, and scopes.

Endpoint	URL
Authorization Server Metadata	`https://api.charmiq.ai/.well-known/oauth-authorization-server`
Protected Resource Metadata	`https://api.charmiq.ai/.well-known/oauth-protected-resource`
Authorization	`https://api.charmiq.ai/oauth/authorize`
Token	`https://api.charmiq.ai/oauth/token`
Dynamic Client Registration (RFC 7591)	`https://api.charmiq.ai/oauth/register`
User Info	`https://api.charmiq.ai/oauth/userinfo`

Claim	Meaning
`sub`	The CharmIQ user
`org`	The Organization the user selected during consent
`scope`	The space-delimited scopes that were actually granted

Scope	What It Grants
`richtext.read`	Read documents, Charms, chats, collections, assets
`richtext.write`	Create, update, delete documents and related resources

Token	Lifetime	Notes
Authorization code	10 minutes	Single-use
Access token	1 hour	Refresh before expiry
Refresh token	30 days	Rotated on every refresh — the new refresh token replaces the old one
Dynamic client	Cleaned up after 90 days of inactivity	Re-register if your client goes idle for long stretches

MCP Authentication

Discovery Endpoints

The Flow

Scopes

Token Lifetimes

Server-to-Server Clients

Calling an MCP Endpoint

Revocation and Visibility

Patterns

Next Steps