Getting Started
Authentication
Two distinct systems: how a person signs in to the BotForge dashboard, and how your server authenticates to the REST API.
Session auth (dashboard)
JWT sessions (30-day rolling), backed by NextAuth (src/auth.ts) with a Prisma adapter. Every OAuth provider follows the same conditional pattern — dormant (button hidden) until its env vars are configured.
| Email + password | Always on. bcrypt hash, brute-force lockout, optional TOTP second factor. |
| Google / GitHub | Enabled once the matching OAuth env vars are configured — dormant otherwise. |
| Microsoft (Entra ID) | OAuth via next-auth/providers/microsoft-entra-id. Omitting a tenant ID uses the multi-tenant "common" issuer. |
| Telegram Login Widget | Signed-payload verification against the bot token. |
| Enterprise SSO | An organization's IdentityProvider (OIDC family). One shared sso Credentials provider exchanges a one-time ticket — never a NextAuth provider per IdP. |
Registration is two steps: pick a goal (Business / Agency / Developer / Enterprise — a marketing persona stored on Workspace.goal, never an RBAC role), then account details. One transaction creates the User, Workspace, an OWNER membership, a Free subscription and default AI settings.
Enterprise SSO
Typing a work email into the login form runs a read-only domain lookup on blur. If the domain matches a VERIFIED organization domain with an ACTIVE identity provider, the form offers “Continue with {Company}'s SSO”, redirecting to /api/sso/[org]/start. Full provider setup, SCIM provisioning and domain verification are covered on the Enterprise page — this page only covers the login-time behavior.
API key auth (REST API)
Your integration never uses a dashboard session — it authenticates with a scoped API key created under Developers → API keys, sent as a Bearer token. Full endpoint list, rate limits and error codes are on the API Reference.
curl https://bot-forge-coral.vercel.app/api/v1/customers \
-H "Authorization: Bearer bf_live_xxx"Session security
Every sign-in writes a LoginActivity row (IP, user agent, timestamp), visible under Account & Security. Sign out everywhere bumps User.sessionVersion, checked on every request's JWT callback — the platform's session-revocation primitive. Error messages never distinguish “wrong password” from “no such account” (anti-enumeration).