White Label Authentication
for SaaS Platforms

curl -X POST https://auth-api.z101.ai/api/admin/tenants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme",
    "branding": {
      "sms_sender_name": "Acme",
      "sms_template": "Your {name} code is: {code}. Expires in {expiry} minutes.",
      "logo_url": "https://acme.com/logo.png",
      "primary_color": "#2563eb",
      "login_page_title": "Sign in to Acme",
      "support_email": "support@acme.com"
    },
    "settings": {
      "otp_length": 6,
      "otp_expiry_minutes": 10,
      "max_otp_attempts": 5,
      "rate_limit_per_hour": 5,
      "voip_blocking": true
    }
  }'

# Response:
{
  "tenant_id": "tn_acme_7f3a...",
  "api_key": "auth1_pk_acme_a8b2c3d4e5f6...",
  "name": "Acme Corp"
}

// When this request is made with Acme's API key,
// the SMS will say: "Your Acme code is: 482913"
// No branding config needed in the request itself.

const response = await fetch('https://auth-api.z101.ai/api/auth/request', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'auth1_pk_acme_a8b2c3d4e5f6...'
  },
  body: JSON.stringify({
    phone: '+15551234567'
  })
});

// The user receives:
// "Your Acme code is: 482913. Expires in 10 minutes."

// When a new customer signs up for your SaaS platform,
// automatically provision an Auth1 tenant for them:

async function provisionTenant(customer) {
  const tenant = await fetch('https://auth-api.z101.ai/api/admin/tenants', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${ADMIN_TOKEN}`
    },
    body: JSON.stringify({
      name: customer.companyName,
      slug: customer.slug,
      branding: {
        sms_sender_name: customer.companyName,
        logo_url: customer.logoUrl,
        primary_color: customer.brandColor,
        login_page_title: `Sign in to ${customer.companyName}`
      }
    })
  });

  const data = await tenant.json();

  // Store the API key in your database
  // Use it for all auth requests for this customer's users
  await db.customers.update(customer.id, {
    auth1_api_key: data.api_key,
    auth1_tenant_id: data.tenant_id
  });

  return data;
}

// Auth1 webhook payload
{
  "event": "auth.verified",
  "tenant_id": "tn_acme_7f3a...",
  "tenant_name": "Acme Corp",
  "user": {
    "phone": "+15551234567",
    "user_id": "usr_abc123",
    "is_new": true
  },
  "risk": {
    "score": 0.12,
    "line_type": "mobile",
    "carrier": "T-Mobile",
    "voip": false
  },
  "timestamp": "2026-03-23T14:22:31Z"
}

// Your webhook handler can route by tenant
app.post('/webhooks/auth1', async (req, res) => {
  const { event, tenant_id, user, risk } = req.body;

  if (event === 'auth.verified') {
    // Find the customer in your database by tenant_id
    const customer = await db.customers.findBy({
      auth1_tenant_id: tenant_id
    });

    // Create or update the user in the customer's context
    await db.users.upsert({
      customer_id: customer.id,
      phone: user.phone,
      auth1_user_id: user.user_id,
      risk_score: risk.score
    });
  }

  res.sendStatus(200);
});

// Install: npm install @auth1/sdk

import { Auth1Client } from '@auth1/sdk';

// Initialize with the tenant's API key
const auth1 = new Auth1Client({
  apiKey: process.env.AUTH1_API_KEY,  // tenant-specific key
  baseUrl: 'https://auth-api.z101.ai'
});

// Request OTP - SMS is automatically branded
export async function requestOTP(phone) {
  const result = await auth1.requestOTP({ phone });
  return result;
  // SMS sent: "Your Acme Corp code is: 482913"
}

// Verify OTP
export async function verifyOTP(phone, code) {
  const result = await auth1.verifyOTP({ phone, code });

  if (result.verified) {
    // Set session cookie
    cookies().set('auth_token', result.token, {
      httpOnly: true,
      secure: true,
      sameSite: 'lax',
      maxAge: 86400 * 7
    });
  }

  return result;
}

# Add a custom domain for the Acme tenant
curl -X POST https://auth-api.z101.ai/api/admin/tenants/tn_acme_7f3a/domains \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{
    "domain": "login.acme.com",
    "auto_ssl": true
  }'

# Response:
{
  "domain": "login.acme.com",
  "status": "pending_dns",
  "cname_target": "custom.auth1.ai",
  "instructions": "Add a CNAME record: login.acme.com -> custom.auth1.ai"
}

# Once DNS propagates, the hosted login page is live at:
# https://login.acme.com
# Branded with Acme's logo, colors, and login page title