Authentication

BasaltCRM supports multiple authentication methods for different use cases — from user login to service-to-service integration.

NextAuth Session

Browser-based SSO for end users via Google, GitHub, or Azure AD.

OAuth 2.0 + PKCE

Secure authorization code flow for third-party integrations.

x402 Payment Auth

402 Protocol for Agent Commerce with USDC on Base network.

NextAuth.js — User Authentication

BasaltCRM uses NextAuth.js for all user-facing authentication. Users sign in via OAuth providers (Google, GitHub, Azure AD), and sessions are managed server-side with JWT encryption.

Supported Providers

GoogleGOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET

OAuth 2.0 via Google Workspace or personal accounts.

GitHubGITHUB_ID / GITHUB_SECRET

OAuth App for developer-friendly login.

Azure ADAZURE_AD_CLIENT_ID / AZURE_AD_TENANT_ID

Enterprise SSO for Microsoft-centric organizations.

Session Structure

// Server-side: getServerSession(authOptions) { user: { id: "64f...", // MongoDB ObjectId name: "Jane Doe", email: "[email protected]", image: "https://...", role: "ADMIN", // TeamRole enum teamId: "64f...", // Active team scope teamRole: "SUPER_ADMIN" } }

OAuth 2.0 + PKCE — Service Integration

For service-to-service integrations (e.g., BasaltECHO connecting to your CRM), BasaltCRM implements the Authorization Code + PKCE flow. This is the recommended method for third-party applications.

Authorization Request

Redirect the user to the BasaltCRM authorization endpoint.

GET /api/oauth/authorize ?response_type=code &client_id=YOUR_CLIENT_ID &redirect_uri=https://your-app.com/callback &scope=softphone:control outreach:write leads:read &state=random-csrf-string &code_challenge=BASE64URL(SHA256(code_verifier)) &code_challenge_method=S256

User Consent

BasaltCRM presents a branded consent screen. The user approves access, and the browser redirects back to your redirect_uri with an authorization code.

302 → https://your-app.com/callback ?code=auth_a1b2c3d4... &state=random-csrf-string

Token Exchange

Exchange the authorization code for access and refresh tokens.

POST /api/oauth/token Content-Type: application/json { "grant_type": "authorization_code", "code": "auth_a1b2c3d4...", "redirect_uri": "https://your-app.com/callback", "client_id": "YOUR_CLIENT_ID", "code_verifier": "your_original_verifier" }

Token Response

Receive your access token and use it to call BasaltCRM APIs.

{ "access_token": "access_64f..._abc123", "refresh_token": "refresh_64f..._xyz789", "token_type": "Bearer", "expires_in": 3600, "scope": "softphone:control outreach:write leads:read", "user_id": "64f..." }

Available Scopes

Scope	Description
`softphone:control`	Control BasaltECHO voice sessions — start, stop, push prompts.
`outreach:write`	Create and manage outreach sequences and campaigns.
`leads:read`	Read-only access to leads, contacts, and pipeline data.
`leads:write`	Create, update, and delete lead records.
`accounts:read`	Read-only access to account records.
`projects:read`	Access project boards and task data.

x402 Protocol — Agent Commerce

The Agent Commerce API uses the HTTP 402 Payment Required protocol. Clients receive a payment challenge, settle on-chain with USDC on Base, then pass the payment proof in the Authorization: Payment <proof> header.

# 1. Request a resource without payment → 402 challenge GET /api/v1/agent/purchase/agent-sdr-01 # Response: 402 Payment Required { "recipient": "0x_merchant_wallet", "amount": "99.00", "network": "base", "token": "usdc" } # 2. Pay on-chain, then retry with proof GET /api/v1/agent/purchase/agent-sdr-01 Authorization: Payment <on-chain-proof> # Response: 200 OK { "success": true, "resource": "https://agents.basalthq.com/deploy/sdr-01" }

Security Best Practices

• Never expose API keys or OAuth client secrets in client-side code.
• Always use PKCE (S256) for OAuth flows — plain code challenges are rejected.
• Verify webhook signatures using HMAC-SHA256 in production environments.
• Rotate tokens periodically and use short-lived access tokens (1h default).
• Use NEXTAUTH_SECRET with 256+ bits of entropy for JWT encryption.