API Documentation

Multi-Domain Edge Authentication API

Authentication

POST /register
Register a new user account
Request Body
{ "email": "user@example.com", "password": "securepassword123", "name": "John Doe" }
Example Response
{
  "message": "User created. Please check your email to verify your account.",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "John Doe"
  }
}
POST /login
Login with email and password
Request Body
{ "email": "user@example.com", "password": "securepassword123" }
Example Response
{
  "message": "Login successful",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user"
  }
}
POST /magic-link
Send magic link email (automatically sent on email login)
Request Body
{ "email": "user@example.com" }
GET /oauth/google
Initiate Google OAuth login flow
Query Parameters
return_to: string (optional) - URL to redirect after login
POST /logout Auth Required
Logout and revoke current session
GET /session Auth Required
Get current session information
Example Response
{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user",
    "apps": ["app1"],
    "env": ["prod"],
    "userType": "b2c"
  },
  "organization": null,
  "session": {
    "id": "session-id",
    "expiresAt": "2024-01-01T00:00:00Z",
    "targetDomain": "app1.brand1.com",
    "targetSubapp": "app1",
    "targetEnv": "prod"
  }
}

Password Management

POST /forgot-password
Request password reset email
Request Body
{ "email": "user@example.com" }
POST /reset-password
Reset password with token
Request Body
{ "token": "reset-token-from-email", "password": "newpassword123" }

Two-Factor Authentication

POST /auth/2fa/setup Auth Required
Get 2FA setup QR code and backup codes
POST /auth/2fa/enable Auth Required
Enable 2FA with secret and verification code
Request Body
{ "secret": "TOTP_SECRET", "code": "123456" }
POST /auth/2fa/verify
Verify 2FA code during login
Request Body
{ "code": "123456", "sessionId": "temp-session-id" }

MetaMask / Web3

POST /auth/metamask/nonce
Get nonce for MetaMask signature
Request Body
{ "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" }
POST /auth/metamask/verify
Verify MetaMask signature and login
Request Body
{ "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "signature": "0x...", "message": "Sign in message", "nonce": "nonce-from-previous-request" }

API Keys

POST /keys Auth Required
Create a new API key
Request Body
{ "name": "My API Key" }
GET /keys Auth Required
List all API keys for current user
DELETE /keys/:id Auth Required
Revoke an API key

Public Endpoints

GET /health
Health check endpoint
GET /.well-known/jwks.json
JWKS (JSON Web Key Set) for JWT verification
GET /branding
Get branding configuration for current domain
GET /verify-email
Verify email address with token
Query Parameters
token: string (required) - Verification token from email

Authentication

Cookie-based: Most endpoints use HTTP-only cookies for authentication. The cookie is set automatically on login and sent with subsequent requests.

API Key: For programmatic access, use API keys created via /keys endpoint. Include in Authorization header:

Authorization: Bearer YOUR_API_KEY

Base URL

All endpoints are relative to:

https://auth.oflo.ai