MCP Authentication

CRM Factory uses OAuth 2.0 authorization_code with PKCE (S256) for all MCP and API access. This is the same flow used by GitHub, Google, and other modern OAuth providers.

OAuth Flow

Step 1: Create an OAuth Client

In the CRM Factory UI, go to Settings → API and click Create Client.

You'll receive a client_id (prefixed crm_) and a client_secret. The secret is shown once — store it securely.

Step 2: Authorization Request

Open the user's browser to:

GET /oauth/authorize
  ?response_type=code
  &client_id=crm_xxxxxxxx
  &redirect_uri=http://localhost:5173/callback
  &scope=crm:read crm:write
  &state=random_state_value
  &code_challenge=BASE64URL(SHA256(code_verifier))
  &code_challenge_method=S256

The user logs in (if not already), sees the consent screen listing the requested scopes, and clicks Allow.

Step 3: Token Exchange

After approval, the user is redirected to your redirect_uri with a code query parameter:

http://localhost:5173/callback?code=AUTH_CODE&state=random_state_value

Exchange the code for an access token:

curl -X POST https://your-domain.crmfactory.ai/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=http://localhost:5173/callback" \
  -d "client_id=crm_xxxxxxxx" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

Response:

{
  "access_token": "cfat_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "crm:read crm:write"
}

Step 4: Use the Token

Include the access token in all MCP requests:

Authorization: Bearer cfat_...

Tokens expire after 1 hour. When a token expires, repeat the authorization flow to obtain a new one.

Revoking Access

Admins can revoke OAuth clients from Settings → API by clicking Revoke next to the client. This immediately invalidates all access tokens issued to that client.

Discovery Endpoints

These endpoints follow the OAuth 2.0 discovery standards and are used by MCP clients that support automatic configuration.