Public Auth Docs

FWD Auth API

`auth.fwd.dev` is the shared identity layer for FWD apps and white-label services. It supports direct embedded signup/login plus standard OAuth authorization flows.

Machine-readable spec Open app

Embedded Auth

Register users from another app

Use this when your white-label app owns the sign-up screen but you want credentials stored centrally in FWD Auth.

POST /api/embedded/register
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "external_user_id": "app-user-123",
  "email": "ada@example.com",
  "password": "correct horse battery staple",
  "fullName": "Ada Lovelace"
}

Central Login

Authenticate against the shared account

Use this when the user logs in on your app, but the password check should happen against the central omni-auth account.

POST /api/embedded/login
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "email": "ada@example.com",
  "password": "correct horse battery staple"
}

2FA Setup

Enable TOTP for a user account

Users enable 2FA after signing in on `auth.fwd.dev`. Call setup, show the secret or otpauth URL, then verify one authenticator code.

POST /api/2fa/setup
Cookie: fwd_auth_session=...

POST /api/2fa/enable
Content-Type: application/json
Cookie: fwd_auth_session=...

{
  "code": "123456"
}

2FA Challenge

Finish sign-in with a TOTP code

When login returns `requiresTwoFactor`, send the challenge ID plus the 6-digit code to the matching verification endpoint.

POST /api/auth/login/2fa
Content-Type: application/json

{
  "challengeId": "challenge_...",
  "code": "123456"
}

POST /api/embedded/login/2fa
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "challengeId": "challenge_...",
  "code": "123456"
}

OAuth Flow

Redirect-based authorization

For browser SSO and delegated profile access, redirect the user to the authorize endpoint, then exchange the returned code for a bearer token.

GET /oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=profile%20email&state=opaque-state

First-Party Apps

Provision FWD Labs clients without shared credentials

Use the internal provisioning API to create one client per app while still marking it as a trusted FWD Labs integration.

POST /api/internal/apps/provision
Authorization: Bearer INTERNAL_PROVISIONING_TOKEN
Content-Type: application/json

{
  "ownerUserId": "usr_owner...",
  "name": "FWD Billing",
  "redirectUris": ["https://billing.fwd.dev/callback"],
  "isFirstParty": true,
  "trustedOrg": "FWD Labs, LLC",
  "defaultScopes": ["profile", "email"]
}

Important

Embedded login centralizes credentials, but true browser SSO still needs a top-level redirect to `auth.fwd.dev` because modern browsers restrict third-party cookies.