# Minds auth.md

Minds provides authenticated access to Minds, Audiences and Studies through REST and MCP.

## Register a read-only agent

Discover [MCP protected resource metadata](/.well-known/oauth-protected-resource/mcp) and [authorization server metadata](/.well-known/oauth-authorization-server). The agent_auth block describes this service's anonymous registration and user-approved claim flow.

1. POST JSON to /agent/register with type "anonymous", requested_credential_type "access_token", client_name, and scope. Supported account scopes are "sparks:read" (Minds and Audiences) and "flows:read" (Studies and results). Omit scope to request both; unsupported or write scopes are rejected.
2. The response includes registration_id, credential, claim_token, claim_url, and expiry. This initial credential has only agent:status scope: send it as Authorization: Bearer to GET /agent/status to inspect this registration. It cannot access account data or call MCP tools. Keep it private and in memory during the ten-minute claim window.
3. POST claim_token and the intended user's email as JSON to claim_url. Read claim_attempt.verification_uri, user_code, expires_in, and interval. Show the link and six-digit code to the user. They must sign in to that email's verified Minds account, enter the code on the Minds page, and approve the displayed read scopes. Do not collect their password, login code, cookies, or the consent form's nonce. No email is sent by this flow.
4. Poll POST /oauth/token as application/x-www-form-urlencoded using grant_type=urn:workos:agent-auth:grant-type:claim and claim_token. Wait at least five seconds between polls. authorization_pending means consent is outstanding; slow_down means wait longer; access_denied and expired_token mean stop. A claim cannot be rebound to another email or restarted; begin a new registration after expiry or denial.
5. A successful single-use exchange returns access_token, refresh_token, token_type, expires_in, and scope. The claim credential is consumed. Store the OAuth credentials in the client's credential store and use Authorization: Bearer. Refresh through /oauth/token with grant_type=refresh_token. Revoke by POSTing token to /oauth/revoke; the user can also remove the OAuth connection in Settings.

These grants read only GET/HEAD /api/v1/minds, /api/v1/audiences, /api/v1/studies, and individual resources beneath those paths (also available under /v1). They can use corresponding MCP read tools; tools requiring other endpoints or write scopes are unavailable. Tokens are bound to the MCP resource /mcp and cannot authenticate browser/account-management endpoints, create API keys, modify research, or run paid work. Registration never creates a user account or grants access before approval.

Public pages, including the homepage and blog, remain anonymously readable. Their discovery documents describe optional service authentication and have no required reading scopes; use the separate /mcp resource metadata for authenticated research.

## MCP: OAuth authorization code with PKCE

Connect to [the MCP endpoint](/mcp). Discover its exact resource identifier and authorization server at [MCP protected resource metadata](/.well-known/oauth-protected-resource/mcp), then read [authorization server metadata](/.well-known/oauth-authorization-server).

Register an OAuth client through the advertised registration_endpoint (/oauth/register). Registration requires an approved redirect URI; unapproved integrations must arrange access before registering. Registration creates a client, not a user account or access token. Open the authorization_endpoint for the user to sign in and consent, using an S256 code challenge. Exchange the authorization code and verifier at the token_endpoint. Send the resulting access token in the Authorization: Bearer header. Use the resource identifier returned by the metadata; it ends in /mcp.

Scope strings in discovery metadata are wire compatibility identifiers. Request only the scopes needed. Never ask users to paste passwords or browser cookies into an agent. Tokens and API keys must stay in the client's credential store.

## REST: user-provisioned API key

The user creates an API key in their Minds account settings. Send it in the Authorization: Bearer header to /api/v1 endpoints. An agent must not assume permission to run billable research from discovering these endpoints.

## References

- [MCP setup](/mcp/setup)
- [REST authentication](/docs/api/authentication)
- [Agent guide](/docs/api/agents)
- [API catalog](/.well-known/api-catalog)