# auth.md

How an AI agent authenticates with mindmap.io.

mindmap.io is agent-first mindmapping software, built for the AI era. Its node
API lets an agent create maps, build node trees, and run generation on a
node. This document tells you how to get a credential and how to send it.

## Who this is for

Autonomous agents and the tools that configure them: MCP clients, agent
frameworks, scripts, and anything else calling mindmap.io without a human in
the request path.

## Two methods

**OAuth 2.1 — use this one.** mindmap.io runs its own authorization server. An
agent registers itself, sends its user through a consent screen, and gets a
scoped access token bound to that person's account. Nothing is pasted, and the
person can see exactly what they approved.

**Bearer token (personal access token).** A long-lived credential a person mints
once in the app and hands to an agent. It is not scoped and it is not
delegated: the token simply *is* the user. It stays supported for clients that
cannot do OAuth.

## OAuth 2.1

### Discovery

| Document | URL |
| --- | --- |
| Protected resource metadata (RFC 9728) | `https://mindmap.io/.well-known/oauth-protected-resource/mcp` |
| Authorization server metadata (RFC 8414) | `https://mindmap.io/.well-known/oauth-authorization-server` |

Both are public and unauthenticated. Read the protected resource document
first: it names the canonical resource and the one authorization server that
issues tokens for it. Everything below is restated from those documents, which
are generated at runtime and are the authority if the two ever disagree.

### What is supported

- **Grants**: `authorization_code` and `refresh_token`. There is no
  `client_credentials` grant — every connection is a specific person's
  delegation, so every connection needs that person's consent.
- **PKCE**: required, `S256` only.
- **Client authentication**: `none`. Every client here is public, and a secret a
  public client has to ship is not a secret. PKCE authenticates the exchange.
- **Client ID Metadata Documents**: supported, and preferred. Host a client
  metadata document and pass its https URL as your `client_id`; there is then
  nothing to register.
- **Dynamic client registration (RFC 7591)**: supported, at
  `https://mindmap.io/api/oauth/register`, as the fallback for clients that
  cannot host a metadata document. It is rate-limited per IP.
- **Resource indicators (RFC 8707)**: required in practice. Pass
  `resource=https://mindmap.io/mcp` on the authorization request. Tokens are
  bound to that audience and the resource server refuses a token issued for
  anything else.
- **Issuer identification (RFC 9207)**: authorization responses carry `iss`.
  Check it.

### Scopes

| Scope | What it allows |
| --- | --- |
| `read` | Read maps, nodes, subtrees and uploaded files. |
| `write` | Everything `read` allows, plus creating, editing, deleting, publishing, running generation and sending feedback. |

`write` implies `read`. Ask for what you need: the consent screen offers the
person a read-only choice, and a connection granted `read` is shown only the
read tools.

The authorization server metadata lists a third scope, `offline_access`. Append
it if your client expects to; it is accepted, and it is also unnecessary. No
grant records it, no token response echoes it back, and the consent screen never
shows it — every connection is issued a rotating refresh token whether it asks
for one or not. The protected resource document lists only `read` and `write`,
because those are the scopes reaching the MCP server can actually require.

### Refresh and revocation

Refresh tokens rotate: each refresh returns a new one and invalidates the one
you sent. Replaying a spent refresh token, or an authorization code, revokes the
whole connection — a legitimate client never replays a credential it has already
exchanged. A dead refresh token answers `invalid_grant`.

There is no revocation endpoint. Consent is revoked by the person who granted
it.

### The hosted MCP server

`https://mindmap.io/mcp` is a remote MCP server over Streamable HTTP, protected
by the OAuth above. It exposes one tool per documented API operation.

In Claude, add it as a custom connector by URL. In Claude Code:

```
claude mcp add --transport http mindmapio https://mindmap.io/mcp
```

An unauthenticated request to it answers `401` with a `WWW-Authenticate` header
naming the protected resource metadata, which is where the flow above starts.

## API tokens

For a client that cannot do OAuth, a person provisions a token in the app:

1. Sign in at `https://mindmap.io/app/`.
2. Open settings, then **API access**.
3. Generate a token and copy it. It is shown once.

Send it as a bearer credential on every request:

```http
GET /api/mindmaps HTTP/1.1
Host: mindmap.io
Authorization: Bearer <your personal access token>
```

A request without a valid token gets `401`. An API token acts as the user who
created it, with that user's full access to their own maps — there is no scope
on one, so treat it as equivalent to the account. Regenerating the token in
settings stops the previous one immediately.

## What a credential can do

Generation calls are metered against the user's plan, whichever credential made
them. When a plan's allowance is exhausted the API answers `429` with a JSON
body describing the limit; a capability the plan does not include answers `403`.
Both are expected states, not transport failures, so handle them rather than
retrying blindly.

## Machine-readable description

The full API, including every endpoint, request shape, and error, is published
as OpenAPI 3.1 at `https://mindmap.io/api/openapi.json`, and catalogued at
`https://mindmap.io/.well-known/api-catalog`. The MCP server's tools are
generated from that same document, so the two cannot describe different
products.

For an installable surface rather than raw HTTP, connect the hosted MCP server
at `https://mindmap.io/mcp`. Setup guides, one per client:

- Claude: `https://mindmap.io/blog/connect-claude-to-mindmap-io/`
- ChatGPT: `https://mindmap.io/blog/add-mindmap-io-to-chatgpt/`
- Claude Code: `https://mindmap.io/blog/add-mindmap-io-to-claude-code/`
- Codex: `https://mindmap.io/blog/add-mindmap-io-to-codex/`
- VS Code: `https://mindmap.io/blog/add-mindmap-io-to-vs-code/`
- Gemini: `https://mindmap.io/blog/add-mindmap-io-to-gemini/`
- Perplexity: `https://mindmap.io/blog/add-mindmap-io-to-perplexity/`
- OpenClaw: `https://mindmap.io/blog/add-mindmap-io-to-openclaw/`
- Hermes Agent: `https://mindmap.io/blog/add-mindmap-io-to-hermes-agent/`

For a
client that cannot do OAuth, the stdio server and agent skill are described at
`https://mindmap.io/blog/install-mindmap-io-in-your-agent/`, and the skill index
is at `https://mindmap.io/.well-known/agent-skills/index.json`.