Authentication

Every MindWiki request authenticates with one of two credentials. Pick based on what's calling.

Personal API key (REST + legacy MCP)

For scripts, automations, and AI clients that can't use remote MCP / OAuth.

Get a key

1. Sign in at mindwiki.io.
2. Go to mindwiki.io/account/api-keys.
3. Click Create key, name it, pick scopes (read, write, or both).
4. Copy the key. It's shown exactly once.

Keys start with mw_.

Using a key with REST

Send the key in a Bearer header:

Authorization: Bearer mw_xxxxxxxxxxxxxxxx

Using a key with MCP (legacy fallback)

For MCP clients that don't speak remote OAuth, append the key as a query parameter:

https://api.mindwiki.io/mcp?token=mw_xxxxxxxxxxxxxxxx

The same scope rules apply.

Scopes

Calling a tool or endpoint that requires a scope your key doesn't include returns:

{
  "error": "API key does not include write scope",
  "code": "INSUFFICIENT_SCOPE",
  "required_scope": "write"
}

with HTTP 403.

OAuth (recommended for AI clients)

For Claude.ai, Claude Desktop, ChatGPT, and other AI clients that support remote MCP.

Connection

Add https://api.mindwiki.io/mcp as a remote MCP server in your AI client. The client discovers OAuth metadata and triggers a browser approval on mindwiki.io. After approval, the client receives a token with the approved scope. External connector tokens authorize MCP access, not general REST access.

The Muse connector is being prepared for this flow; directory approval and live verification are pending.

Endpoints

For client implementers building OAuth flows:

• Issuer: https://api.mindwiki.io
• Discovery (resource): https://api.mindwiki.io/.well-known/oauth-protected-resource
• Discovery (auth server): https://api.mindwiki.io/.well-known/oauth-authorization-server
• Authorize: https://mindwiki.io/oauth/authorize
• Token: https://api.mindwiki.io/oauth/token
• Register (DCR): https://api.mindwiki.io/oauth/register
• Revoke: https://api.mindwiki.io/oauth/revoke
• Code challenge: S256 (PKCE required)
• Grant types: authorization_code, refresh_token
• Scopes: mcp:read, mcp:capture, mcp:write, and legacy mcp
• Resource: https://api.mindwiki.io/mcp

OAuth permissions

Clients should request space-separated scopes appropriate to the task. For example, mcp:read mcp:capture supports retrieval and saving captures without arbitrary page edits. The approval page can reduce a compatible request, so clients must use the returned grant rather than assume full access. Vault agent permissions are an additional check.

Cancellation returns access_denied to the registered callback, preserving state. Reconnecting is required after revocation. Do not treat an OAuth client display name or self-declared software ID as verified identity. Protect authorization codes and tokens from logs.

MCP scope failures use an MCP error response. The HTTP error table below describes REST responses.

Refresh and recovery

External OAuth refresh tokens rotate. Store the returned access and refresh tokens together before making another refresh request. A token expires after 30 days without refresh, with a 90-day maximum grant lifetime. Reconnect after expiry.

If a refresh response is lost, retry the same refresh token and scope within 60 seconds to recover the same replacement pair. A replay after that window revokes only that grant and requires reconnection. Do not run independent refresh loops or reuse older tokens after a successful refresh. Revocation takes effect even during recovery.

Provisioned MindWiki native applications have a separate stable-refresh policy. It is not available through public client registration.

Errors

Security guidance

• Use scoped keys. A key for a read-only integration should not have write.
• One key per integration. Granular keys make revocation painless.
• Don't commit keys to source. Use environment variables or a secrets manager.
• Rotate after exposure. Revoke and re-mint immediately if a key may have leaked.
• Audit periodically. The keys list shows last-used timestamps.