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

Sign in at mindwiki.io.
Go to mindwiki.io/account/api-keys.
Click Create key, name it, pick scopes (read, write, or both).
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

Scope	Allows
`read`	Search, read, list, ask, similar, graph, lint, export, stats
`write`	Capture, create / update / delete pages, rebuild index, create proposals

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

json

{
  "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 that grants both read and write scopes.

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
Scope: mcp

Errors

HTTP	Code	Meaning
401	`TOKEN_INVALID`	The key was revoked, mistyped, or never existed
403	`INSUFFICIENT_SCOPE`	The key is valid but lacks the required scope
409	`CONFLICT`	Optimistic concurrency mismatch on a write — see the response body for the current hash
429	(none)	Rate limited — retry after the time in `Retry-After`

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.