# Authenticating an agent to Ormind

Ormind has one protected resource for agents: the MCP server at `https://app.ormind.ai/api/mcp`. Every request carries a bearer token that belongs to one Ormind member, and the agent acts with that member's rights. There is no anonymous access and no service account: an agent always works for a person who signed in.

Full integration guide: https://www.ormind.ai/developers.md

## Discover

1. Call the MCP endpoint without a token. It answers HTTP 401 with:
   `WWW-Authenticate: Bearer resource_metadata="https://app.ormind.ai/.well-known/oauth-protected-resource/api/mcp"`
2. Read that protected resource metadata (RFC 9728). It names the `resource`, the `authorization_servers` (Ormind signs members in through Auth0), `bearer_methods_supported` (`header`) and `scopes_supported`.
3. Read the authorization server metadata (RFC 8414) at `<authorization server>/.well-known/oauth-authorization-server`. `https://app.ormind.ai/.well-known/oauth-authorization-server` redirects there for older MCP clients.

## Pick a method

| Method | For | Token |
|---|---|---|
| OAuth 2.1 authorization code with PKCE | Claude.ai, the Claude apps, ChatGPT, any MCP client with a browser sign-in | A JWT issued by Auth0 for the resource `https://app.ormind.ai/api/mcp` |
| Personal agent token | Claude Code, Codex, Cursor, scripts | An opaque token starting with `cg_` |

## Register

- **OAuth:** use the pre-registered public client ID that Ormind shows on https://www.ormind.ai/connect.html (one for Claude, one for ChatGPT). Do not rely on dynamic client registration: the sign-in service caps how many dynamic clients it keeps, and the connection would fail.
- **Agent token:** the member signs in at https://app.ormind.ai, opens their connections (`/?connections=1`) and generates the token. It is shown once.

## Scopes

- `workspace:read`: read tools only. Writing tools are hidden from the agent.
- `workspace:write`: read and write, within the member's role in each dossier.

The member chooses read only, or read and write, on the consent screen.

## Exchange

Standard OAuth: send the member to the authorization endpoint with `response_type=code`, your client ID, a PKCE `code_challenge`, the `audience`/`resource` `https://app.ormind.ai/api/mcp` and the scopes you need. Exchange the returned code at the token endpoint for an access token.

## Use the access_token

Send it on every MCP request:

```
POST https://app.ormind.ai/api/mcp
Authorization: Bearer <access_token or cg_ token>
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}
```

Then call `tools/list` and `tools/call`. Start with the `list_workspaces` tool.

## Errors

| Status | Meaning | What to do |
|---|---|---|
| 401, `error="invalid_token"` | Missing, expired, revoked or unknown token | Sign in again, or ask the member for a new agent token |
| 403, `error="insufficient_scope"` | The token lacks the scope the request needs | Ask the member to reconnect with read and write |
| 429 with `Retry-After` | More than 60 requests per minute on one connection | Wait the given seconds, then retry |
| Tool result starting with `⛔ BLOCKED` | The member's role forbids this action | Do not retry; tell the member |

## Revocation

- OAuth: the member removes or disconnects the Ormind connector in their assistant's settings.
- Agent token: generating a new token in Ormind revokes the previous one immediately.
- Deleting the Ormind account revokes everything.

Security questions: contact@ormind.ai