# CareerMax auth.md

> How an AI agent or MCP client connects to CareerMax on a user's behalf. Every connection needs a person with a CareerMax account who signs in and approves it. There are no API keys, and agents cannot register accounts or themselves.

## Who this is for

AI assistants and MCP clients acting for one signed-in CareerMax user. Reading public pages needs no sign-in: every careermax.ai page returns Markdown when requested with `Accept: text/markdown`, and the docs index is at https://careermax.ai/llms.txt.

## Connect

- MCP server: https://mcp.careermax.ai/mcp (Streamable HTTP transport). Server Card: https://mcp.careermax.ai/mcp/server-card
- Protected resource metadata (RFC 9728): https://mcp.careermax.ai/.well-known/oauth-protected-resource/mcp. Bearer tokens go in the `Authorization` header only.
- Authorization server (RFC 8414): https://clerk.careermax.ai, metadata at https://clerk.careermax.ai/.well-known/oauth-authorization-server. Read it for the authorization and token endpoints.
- An unauthenticated request to the MCP server returns `401` with a `WWW-Authenticate` header whose `resource_metadata` points at the URL above.

## Authorize

1. Identify your client with a Client ID Metadata Document: the `client_id` is the HTTPS URL of your client's metadata JSON.
2. Run the OAuth 2.1 authorization code flow with PKCE (`S256`). Send `resource=https://mcp.careermax.ai/mcp` (RFC 8707) on the authorization and token requests. Tokens issued for another resource are rejected.
3. The user signs in with their CareerMax account in the browser and approves access. New users accept the CareerMax Terms and Privacy Policy while signing up. Your agent never sees their password.
4. Call the MCP server with `Authorization: Bearer <access token>`. Use the refresh token (scope `offline_access`) to stay connected.

## Clients

- Pre-registered (Client ID Metadata Documents): Claude (claude.ai on web, desktop and mobile), Claude Code, ChatGPT, Hermes Agent, Grok, and Grok Bot and Cursor (Cursor's client). These hosts get every scope below.
- Any other MCP client can register itself (RFC 7591 dynamic client registration) and connect with `careermax:read` and `careermax:write` only. Anyone can register a client under any name, so these clients never get the scopes that apply, submit, spend credits, send email or read sensitive answers, and those tools aren't listed for them. To request full access for another assistant, contact support.

## Scopes

- `careermax:read`: Read the user's profile, jobs, applications, stories and credits.
- `careermax:write`: Save the profile, job preferences, answers and interview stories.
- `careermax:external`: Start work that reaches other services or uses credits: applications, contact search, company research, employer email replies.
- `careermax:submit`: Submit an application the user approved.
- `careermax:sensitive`: Read sensitive application answers the user gave.
- `careermax:events`: Subscribe to application status events.
- Also requested: `openid`, `profile`, `email`, `offline_access`.

Whatever the scopes, an application started through the connector is submitted only after the user approves it in the chat or taps Submit in the card.

## Errors

- `401`: missing, invalid or expired token. Refresh it, or run the sign-in again.
- `403`: the client is not allowed, the token lacks a required scope (the `WWW-Authenticate` header names it), or the user has not finished signing up or accepting current terms. Ask the user to finish at https://careermax.ai.
- `503`: sign-in verification is temporarily unavailable. Retry shortly.

## Registration

Agents can't create CareerMax accounts. People create them at https://careermax.ai, or while signing in during the first connection. Clients identify themselves with a Client ID Metadata Document, or register through the authorization server's `registration_endpoint` (see its metadata) with the limits above.

## More

- For AI agents and developers: https://careermax.ai/docs/for-ai-agents
- Setup steps for people: https://careermax.ai/docs/set-up-claude.md
- All CareerMax docs for agents: https://careermax.ai/llms.txt
- API catalog (RFC 9727): https://careermax.ai/.well-known/api-catalog
- Agent skills index: https://careermax.ai/.well-known/agent-skills/index.json
- Support: hey@careermax.ai