OAuth & authentication

Sign in, API tokens, OAuth for MCP, and SSO/SCIM for Business teams.

OAuth & authentication

One Molar account signs you in everywhere — dashboard, REST API, CLI, and MCP. You do not create separate logins per product.

Browser sign-in

Sign in at app.molar.it with:

  • Magic link
  • GitHub or Google OAuth (all tiers)
  • Email/password where enabled

Sessions are org-scoped. API clients that manage multiple orgs should send x-org-id on requests (the dashboard sets this automatically).

OAuth for MCP and API clients

MCP clients (Cursor, Claude Code, etc.) complete OAuth 2.1 + PKCE against https://api.molar.it. OAuth routes are mounted at /api/oauth/* on the auth host.

EndpointPurpose
GET /.well-known/oauth-authorization-serverAuthorization server metadata (on api.molar.it)
GET /.well-known/oauth-protected-resourceMCP resource metadata (on mcp.molar.cloud)
POST /api/oauth/registerDynamic client registration
GET /api/oauth/authorizeAuthorization code + PKCE
POST /api/oauth/tokenToken exchange + refresh
POST /api/oauth/revokeToken revocation

MCP scopes

ScopePurpose
mcp:readList/get scenarios, runs, incidents, traces
mcp:writeCreate/update resources, Mender PR review
mcp:runTrigger Guard scenario runs
mcp:clone:writeCloud clone lifecycle
mcp:trace:readTrace replay
mcp:debugAI debugger (billed)
mcp:exploreBrowse/map external sites
mcp:actState-changing actions on external sites
mcp:identityProvision test identities, read OTP/messages

Token policy

SettingValue
PKCEMandatory, S256 only
Access token TTL1 hour
Refresh tokenRotating, 90-day TTL
Token formatOpaque + Redis introspection cache (60s)
Resource indicatorRequired: resource=https://mcp.molar.cloud

MCP tools validate audience and scopes per call (confused-deputy defense). Agent signup tokens are service tokens (molar_svc_*) with scopes managed by the agent-signup flow until the human verifies.

Personal & service tokens

Create tokens in the dashboard:

Settings → Tokens → Create token

TypeUse case
PAT (Personal Access Token)CLI, scripts, local MCP with --cloud-access
SVC (Service token)CI, GitHub Actions, server integrations

Revoke anytime; revocations propagate within the introspection cache window.

export MOLAR_TOKEN=molar_pat_xxxx
curl -H "Authorization: Bearer $MOLAR_TOKEN" \
     -H "x-org-id: org_xxxx" \
     https://api.molar.it/api/v1/me

Org roles (RBAC)

RoleAccess
ownerFull org control, delete org, transfer ownership
adminMembers, settings, billing read, all product features
memberScenarios, runs, traces — no billing admin
billingInvoices and payment methods only

SSO (WorkOS) — Business tier

Enterprise SSO is a Business+ add-on via WorkOS:

  • SAML / OIDC — IT configures IdP through the hosted Admin Portal
  • Dashboard path: app.molar.it/{org}/settings/sso
  • Availability: contact us via app.molar.it for enterprise SSO

SSO failover

If WorkOS is unreachable:

  • Orgs with sso_enforced=false may fall back to magic link for verified domain emails
  • Orgs with sso_enforced=true (default for SSO-enabled orgs) see 503 + status page link

SCIM provisioning

WorkOS Directory Sync pushes to Molar's SCIM endpoints:

  • GET/POST/PUT/PATCH/DELETE /api/v1/scim/v2/Users
  • GET/POST/PUT/PATCH/DELETE /api/v1/scim/v2/Groups

Configure in Settings → SCIM:

  • SCIM bearer token (rotate quarterly)
  • Per-org scim_secret so a leak affects one customer
  • Directory sync status

SCIM maps to users, memberships, and groups tables for JIT provisioning.

When an MCP client requests scopes, users see a consent screen (OAuth AS) listing tools and permissions. Admin-approved clients can skip re-consent per org policy (Enterprise).

Security practices

  • Argon2id for passwords when password auth is enabled
  • No token passthrough to upstream APIs — MCP uses service credentials
  • Secrets in scenarios resolve via ${secrets.*} — never inlined in compiled output
  • Audit log records OAuth client registrations and token grants (Enterprise retention)