Authentication

Fabric supports native email/password authentication with social login, API keys for service-to-service communication, and JWT validation. The first matching mechanism in the authentication chain is used.

Native Auth (Email/Password)

Native auth is the recommended mode for consumer-facing applications. It handles signup, login, email verification, password reset, and brute force protection directly in Fabric.

Enable it by setting OAUTH_SIGNING_SECRET in your environment.

Signup

TypeScript

const auth = await fabric.auth.signup("alice@example.com", "SecurePass1!");
// auth.access_token, auth.refresh_token, auth.user.id

Python

auth = fabric.signup("alice@example.com", "SecurePass1!")
# Tokens auto-stored on client — subsequent calls are authenticated

curl

curl -X POST https://gofabric.dev/v1/auth/signup \
  -H 'content-type: application/json' \
  -d '{"email":"alice@example.com","password":"SecurePass1!"}'

Password requirements: 8+ characters, uppercase, lowercase, digit, special character.

New users get a personal organization (Owner role) automatically.

Login

TypeScript

const auth = await fabric.auth.login("alice@example.com", "SecurePass1!");

Python

auth = fabric.login("alice@example.com", "SecurePass1!")

curl

curl -X POST https://gofabric.dev/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"alice@example.com","password":"SecurePass1!"}'

Brute force protection: After 5 failed attempts, the account is locked for 15 minutes. Returns 429 with Retry-After header.

Token Refresh

Access tokens expire after 2 hours. Use the refresh token to get a new pair:

TypeScript

const auth = await fabric.auth.refresh(refreshToken);

Python

auth = fabric.refresh_token(refresh_token)

curl

curl -X POST https://gofabric.dev/v1/auth/token/refresh \
  -H 'content-type: application/json' \
  -d '{"refresh_token":"eyJ..."}'

Refresh tokens are single-use — each refresh issues a new pair and blacklists the old refresh token.

Change Password

TypeScript

await fabric.auth.changePassword("OldPass1!", "NewPass1!");

Python

fabric.change_password("OldPass1!", "NewPass1!")

curl

curl -X POST https://gofabric.dev/v1/auth/change-password \
  -H 'Authorization: Bearer eyJ...' \
  -H 'content-type: application/json' \
  -d '{"current_password":"OldPass1!","new_password":"NewPass1!"}'

Changing your password invalidates all existing sessions (logout everywhere).

Logout All Sessions

TypeScript

await fabric.auth.logoutAll();

Python

fabric.logout_all()

curl

curl -X POST https://gofabric.dev/v1/auth/logout-all \
  -H 'Authorization: Bearer eyJ...'

Social Login (Consumer-Driven)

The recommended approach for consumer apps: your app handles the OAuth flow (Google Sign-In, NextAuth, etc.) using your own OAuth credentials, then sends the verified profile to Fabric.

TypeScript

// 1. Your app handles Google Sign-In with YOUR OAuth app
const googleUser = await googleSignIn();

// 2. Send the verified profile to Fabric
const auth = await fabric.auth.socialLogin({
  provider: "google",
  provider_user_id: googleUser.sub,
  email: googleUser.email,
  display_name: googleUser.name,
  avatar_url: googleUser.picture,
});
// auth.access_token, auth.user.id

Python

# 1. Your app handles Google Sign-In
google_user = google_sign_in()

# 2. Send the verified profile to Fabric
auth = fabric.social_login(
    provider="google",
    provider_user_id=google_user["sub"],
    email=google_user["email"],
    display_name=google_user["name"],
)
# Tokens auto-stored — subsequent calls authenticated

curl

curl -X POST https://gofabric.dev/v1/auth/social-login \
  -H 'content-type: application/json' \
  -d '{
    "provider": "google",
    "provider_user_id": "118234567890",
    "email": "alice@gmail.com",
    "display_name": "Alice"
  }'

Account linking logic:

• If this (provider, provider_user_id) is already linked → returns the existing user
• If the email matches an existing user → links the social connection and returns the user
• Otherwise → creates a new user with a personal organization

Why consumer-driven? Each consumer app registers their own Google/GitHub/Apple OAuth app with their own branding and redirect URLs. Fabric doesn’t need any social provider secrets — it just stores the user and social connection link.

Managing Social Connections

TypeScript

// List connected providers
const connections = await fabric.me.socialConnections();

// Disconnect a provider (fails if it's the last auth method)
await fabric.me.disconnectSocial("google");

Python

# List connected providers
connections = fabric.get_my_social_connections()

# Disconnect a provider
fabric.disconnect_social("google")

curl

# List
curl -H 'Authorization: Bearer eyJ...' https://gofabric.dev/v1/me/social-connections

# Disconnect
curl -X DELETE -H 'Authorization: Bearer eyJ...' \
  https://gofabric.dev/v1/me/social-connections/google

Lockout prevention: You cannot disconnect your last auth method. If you only have a Google connection and no password, disconnecting Google is rejected with 409. Set a password first or connect another provider.

Authentication Chain

Fabric resolves authentication in priority order:

1. API Key (Authorization: Bearer fab_*)

API keys are the primary mechanism for service-to-service communication.

TypeScript

const fabric = new FabricClient({ apiKey: "fab_your_api_key_here" });

Python

fabric = FabricClient(api_key="fab_your_api_key_here")

curl

curl -H 'Authorization: Bearer fab_your_api_key_here' \
  https://gofabric.dev/v1/me

Keys use the fab_ prefix, are hashed at rest, and can be org-scoped with configurable expiry and permission scopes.

2. JWT (Authorization: Bearer <jwt>)

JWT tokens issued by Fabric native auth are validated automatically.

3. Dev Header (X-Principal-Id: <uuid>)

For development only. Set FABRIC_ENV=production to disable.

curl -H 'X-Principal-Id: 550e8400-e29b-41d4-a716-446655440000' \
  https://gofabric.dev/v1/me

4. Anonymous

Requests without credentials are anonymous. Only public endpoints (/healthz, /readyz, /openapi.json, auth endpoints) are accessible.

Admin User Management

Admin endpoints for managing users programmatically:

TypeScript

// List users
const { items } = await fabric.admin.listUsers({ limit: 20 });

// Unlock a locked account
await fabric.admin.unlockUser(userId);

// Force-verify email
await fabric.admin.verifyUser(userId);

// Force logout all sessions
await fabric.admin.forceLogoutUser(userId);

// Delete user
await fabric.admin.deleteUser(userId);

Python

# List users
users = fabric.admin_list_users(limit=20)

# Unlock a locked account
fabric.admin_unlock_user(user_id)

# Force-verify email
fabric.admin_verify_user(user_id)

# Force logout all sessions
fabric.admin_force_logout_user(user_id)

# Delete user
fabric.admin_delete_user(user_id)

curl

# List users
curl -H 'Authorization: Bearer fab_xxx' https://gofabric.dev/v1/admin/users

# Unlock
curl -X POST -H 'Authorization: Bearer fab_xxx' \
  https://gofabric.dev/v1/admin/users/<id>/unlock

# Verify email
curl -X POST -H 'Authorization: Bearer fab_xxx' \
  https://gofabric.dev/v1/admin/users/<id>/verify

# Delete
curl -X DELETE -H 'Authorization: Bearer fab_xxx' \
  https://gofabric.dev/v1/admin/users/<id>

CLI User Management

# Create a user (--skip-verification for dev)
fabric user create --email alice@dev.local --password 'Test1234!' --skip-verification

# List users
fabric user list

# Unlock a locked account
fabric user unlock --email alice@dev.local

# Verify email manually
fabric user verify --email alice@dev.local

# Reset password (admin — no old password needed)
fabric user reset-password --email alice@dev.local --new-password 'NewPass1!'

# Delete user
fabric user delete --email alice@dev.local

API Keys

Creating API Keys

TypeScript

const key = await fabric.createApiKey({
  name: "my-service-key",
  organizationId: "<org-id>",
  scopes: ["jobs:write", "providers:execute"],
});
console.log("Store this key:", key.raw_key);  // shown only once

Python

key = fabric.create_api_key(
    name="my-service-key",
    organization_id="<org-id>",
    scopes=["jobs:write", "providers:execute"],
)
print("Store this key:", key["raw_key"])  # shown only once

curl

curl -X POST https://gofabric.dev/v1/api-keys \
  -H 'Authorization: Bearer fab_xxx' \
  -H 'content-type: application/json' \
  -d '{"name":"my-service-key","organization_id":"<org-id>","scopes":["jobs:write"]}'

Scopes

Scope	Description
jobs:write	Create and manage jobs
jobs:read	Read job status and history
providers:execute	Execute provider requests
workflows:write	Create and manage workflows
workflows:read	Read workflow definitions and runs
(empty list)	Full access (no restrictions)

Authorization (RBAC)

Role	Level	Capabilities
Owner	Highest	Full access, can manage other owners
Admin	High	Manage teams, invitations, most resources
Member	Standard	Create and manage own resources
Viewer	Lowest	Read-only access

Roles are scoped to organizations and optionally to teams. Clients must not compute permissions themselves — Fabric is the enforcement authority.

Auth Webhook Events (Consumer Email)

Fabric emits webhook events for all auth actions. Consumer apps can subscribe to these events to send their own branded emails instead of using Fabric’s built-in Resend templates.

Event	Payload	Use case
auth.email_verification_required	principal_id, email, verify_token, verify_url	Send your own verification email
auth.password_reset_requested	principal_id, email, reset_token, reset_url	Send your own password reset email
auth.social_login	principal_id, email, provider, provider_user_id	Welcome email for social signups
auth.password_changed	principal_id	Notify user of password change
auth.account_locked	email	Alert user of lockout (5 failed attempts)
auth.signup	principal_id, email	Welcome email for new signups

Example: Custom Verification Email

Subscribe to auth.email_verification_required via a webhook, then send your own email with the verify_token:

// Your webhook handler receives:
{
  "event": "auth.email_verification_required",
  "payload": {
    "principal_id": "550e8400-...",
    "email": "alice@example.com",
    "verify_token": "a1b2c3d4...",
    "verify_url": "https://fabric.example.com/v1/auth/verify?token=a1b2c3d4...&type=signup"
  }
}

// Build your own verify URL pointing to YOUR frontend:
const myVerifyUrl = `https://app.socialite.com/verify?token=${payload.verify_token}`;

// Your frontend calls Fabric's verify endpoint:
// GET https://fabric.example.com/v1/auth/verify?token=a1b2c3d4...&type=signup

Dual delivery: If RESEND_API_KEY is set, Fabric also sends its own verification/reset emails as a fallback. To use only your own emails, leave RESEND_API_KEY unset and handle the webhook events instead.

Configuration

Variable	Required	Description
OAUTH_SIGNING_SECRET	For native auth	Secret for signing JWT tokens. Generate with openssl rand -hex 32
FABRIC_ENV	No	Set to production to disable dev headers
RESEND_API_KEY	No	Built-in email for verification/reset (optional if using webhooks)
RESEND_FROM_EMAIL	No	Sender email for built-in auth emails
PUBLIC_BASE_URL	No	Base URL for verification/reset links in built-in emails
AUTH_SITE_URL	No	Frontend redirect after email verification
AUTH_CALLBACK_REDIRECT_URL	No	Frontend redirect after social login