Authentication

CRM Factory supports two authentication methods depending on your use case.

Session Cookies (Browser)

The CRM Factory web app uses NextAuth session cookies. When you're signed into the app, API calls from the browser are automatically authenticated via the authjs.session-token cookie.

This is the default for all interactive UI usage — no configuration needed.

OAuth 2.0 Bearer Tokens (API & MCP)

For machine-to-machine access, integrations, and MCP clients, use OAuth 2.0 Bearer tokens.

Obtaining a Token

CRM Factory implements the authorization_code grant with PKCE (S256):

1. Create an OAuth client in Settings → API
2. Redirect the user to /oauth/authorize with your client credentials and PKCE challenge
3. Exchange the authorization code at /api/oauth/token
4. Use the returned access_token as a Bearer token

See the MCP Authentication guide for the full flow with code examples.

Using the Token

Include the token in the Authorization header:

Authorization: Bearer cfat_...

Token Lifetime

Access tokens expire after 1 hour (3600 seconds). The expires_in field in the token response indicates the exact TTL. When a token expires, repeat the authorization flow.

Available Scopes

Revoking Access

Admins can revoke an OAuth client and all its tokens from Settings → API.

Error Responses

Authentication failures return:

{
  "error": "Unauthorized"
}

With HTTP status 401. For OAuth token endpoint errors, the response follows the OAuth 2.0 error format:

{
  "error": "invalid_grant",
  "error_description": "Authorization code is invalid or expired"
}