Authentication

Backflow supports JWT, Firebase Auth, and API keys.

JWT Authentication

Configuration

{
  "jwt": {
    "secret": "{{env.JWT_SECRET}}"
  }
}

Protect Routes

{
  "path": "/admin/users",
  "method": "get",
  "requireAuth": true
}

Making Requests

curl -X GET http://localhost:3000/admin/users \
  -H "Authorization: Bearer <token>"

Generate Tokens

npm run generate-jwt

Access User Data

In route templates:

{
  "data": {
    "user_id": "{{auth.sub}}",
    "role": "{{auth.role}}"
  }
}

Firebase Authentication

Configuration

{
  "firebase": {
    "projectId": "{{env.FIREBASE_PROJECT_ID}}",
    "clientEmail": "{{env.FIREBASE_CLIENT_EMAIL}}",
    "privateKey": "{{env.FIREBASE_PRIVATE_KEY}}"
  }
}

Use Firebase Auth

{
  "path": "/profile",
  "method": "get",
  "authProvider": "firebase"
}

Firebase Token

curl -X GET http://localhost:3000/profile \
  -H "Authorization: Bearer <firebase-id-token>"

Tenant API Keys

API keys are tenant-scoped. The tenant is derived from the key itself - no separate tenant header needed.

Create API Key

Via admin panel or API:

curl -X POST http://localhost:3000/tenant/api-keys \
  -H "Authorization: Bearer <admin-token>" \
  -d '{"name": "Production API", "scopes": ["*"]}'

Response includes the key (shown only once):

{
  "id": "key-123",
  "key": "***",
  "prefix": "***",
  "name": "Production API",
  "scopes": ["*"]
}

Use API Key

curl -X GET http://localhost:3000/api/data \
  -H "x-api-key: <your-api-key>"

No x-tenant-id header needed - tenant is derived from the key automatically.

Key Features

• Securely hashed (original never stored)
• Support scopes for fine-grained access
• Track usage statistics
• Can be rotated with grace period

RBAC (Role-Based Access Control)

Enable RBAC

{
  "rbac": {
    "enabled": true,
    "defaultRole": "user"
  }
}

Protect with Permissions

{
  "path": "/admin/users",
  "method": "delete",
  "requireAuth": true,
  "requiredPermissions": ["users:delete"]
}

Role Endpoints

Method	Endpoint	Description
GET	/rbac/roles	List roles
POST	/rbac/roles	Create role
GET	/rbac/permissions	List permissions
POST	/rbac/assign	Assign role

Multi-Factor Authentication

Enable MFA

MFA is automatically enabled when Supabase and JWT are configured.

MFA Endpoints

Method	Endpoint	Description
POST	/mfa/setup	Generate TOTP secret
POST	/mfa/verify	Verify TOTP code
POST	/mfa/enable	Enable MFA
POST	/mfa/disable	Disable MFA
GET	/mfa/backup-codes	Get backup codes

MFA Flow

1. Call /mfa/setup to get QR code
2. Scan with authenticator app
3. Verify code with /mfa/verify
4. Enable with /mfa/enable

Tenant Authentication

Tenant identity is derived from authentication:

API Key Auth: Tenant derived automatically from the API key

curl -X GET http://localhost:3000/api/data \
  -H "x-api-key: <your-api-key>"

Token Auth: Tenant from claims in JWT/Firebase token

curl -X GET http://localhost:3000/api/data \
  -H "Authorization: Bearer <token>"

Security Best Practices

1. Use strong JWT secrets (32+ characters)
2. Set appropriate token expiration
3. Use HTTPS in production
4. Enable rate limiting
5. Implement MFA for sensitive operations
6. Use RBAC for granular access control