Auth1 API Documentation

Quick Start

Get up and running with Auth1 in under five minutes. Install the SDK, configure your API key, and send your first verification.

1. Install the SDK

npm install @auth1/sdk

yarn add @auth1/sdk

pnpm add @auth1/sdk

2. Initialize and Verify

import Auth1 from '@auth1/sdk';

// Initialize with your API key
const auth = new Auth1({
  apiKey: 'auth1_pk_...'
});

// Send a verification to the user
const result = await auth.verify('user@example.com', '+18005551234');

// result includes VOIP detection + risk score
console.log(result.isVoip);     // false
console.log(result.riskScore);  // 0.12

Authentication

All API requests require an API key passed in the x-api-key header. You can generate keys from your Auth1 Dashboard.

x-api-key: auth1_pk_YOUR_API_KEY
Content-Type: application/json

Key Types

SMS OTP

Send a one-time verification code via SMS. Auth1 automatically detects VOIP numbers and calculates a fraud risk score before delivery.

curl -X POST https://auth-api.z101.ai/api/auth/sms/request \
  -H "Content-Type: application/json" \
  -H "x-api-key: auth1_pk_YOUR_KEY" \
  -d '{
    "phone": "+18005551234",
    "email": "user@example.com",
    "tenant": "your-tenant"
  }'

const res = await fetch('https://auth-api.z101.ai/api/auth/sms/request', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'auth1_pk_YOUR_KEY'
  },
  body: JSON.stringify({
    phone: '+18005551234',
    email: 'user@example.com',
    tenant: 'your-tenant'
  })
});

const data = await res.json();
console.log(data.phoneVerificationId); // uuid
console.log(data.isVoip);               // false
console.log(data.riskScore);            // 0.12

import requests

resp = requests.post(
    "https://auth-api.z101.ai/api/auth/sms/request",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "auth1_pk_YOUR_KEY"
    },
    json={
        "phone": "+18005551234",
        "email": "user@example.com",
        "tenant": "your-tenant"
    }
)

data = resp.json()
print(data["phoneVerificationId"])  # uuid
print(data["isVoip"])               # False
print(data["riskScore"])            # 0.12

Example Response

{
  "phoneVerificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "phoneType": "mobile",
  "isVoip": false,
  "riskScore": 0.12,
  "message": "Verification code sent",
  "provider": "twilio"
}

Email Magic Link

Send a passwordless magic link to the user's email. When clicked, the user is redirected to your callback URL with a verification token.

curl -X POST https://auth-api.z101.ai/api/auth/sms/magic-link/request \
  -H "Content-Type: application/json" \
  -H "x-api-key: auth1_pk_YOUR_KEY" \
  -d '{
    "email": "user@example.com",
    "callbackUrl": "https://yourapp.com/auth/callback"
  }'

const res = await fetch('https://auth-api.z101.ai/api/auth/sms/magic-link/request', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'auth1_pk_YOUR_KEY'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    callbackUrl: 'https://yourapp.com/auth/callback'
  })
});

resp = requests.post(
    "https://auth-api.z101.ai/api/auth/sms/magic-link/request",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "auth1_pk_YOUR_KEY"
    },
    json={
        "email": "user@example.com",
        "callbackUrl": "https://yourapp.com/auth/callback"
    }
)

Example Response

{
  "success": true,
  "message": "Magic link sent"
}

Verify Code

Verify the 6-digit OTP code entered by the user. On success, returns a JWT session token and refresh token.

curl -X POST https://auth-api.z101.ai/api/auth/sms/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: auth1_pk_YOUR_KEY" \
  -d '{
    "phoneVerificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "verificationCode": "123456",
    "email": "user@example.com"
  }'

const res = await fetch('https://auth-api.z101.ai/api/auth/sms/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'auth1_pk_YOUR_KEY'
  },
  body: JSON.stringify({
    phoneVerificationId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    verificationCode: '123456',
    email: 'user@example.com'
  })
});

const { user, token, refreshToken } = await res.json();

resp = requests.post(
    "https://auth-api.z101.ai/api/auth/sms/verify",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "auth1_pk_YOUR_KEY"
    },
    json={
        "phoneVerificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "verificationCode": "123456",
        "email": "user@example.com"
    }
)

data = resp.json()
token = data["token"]

Example Response

{
  "user": {
    "id": "usr_abc123",
    "phone": "+18005551234",
    "email": "user@example.com"
  },
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_d4e5f6a7b8c9..."
}

Session Management

After verification, use these endpoints to manage user sessions. All session endpoints require a Bearer token in the Authorization header.

Get Current Session

curl https://auth-api.z101.ai/api/auth/session \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Refresh Token

curl -X POST https://auth-api.z101.ai/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "rt_d4e5f6a7b8c9..." }'

Logout

curl -X POST https://auth-api.z101.ai/api/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Webhooks

Auth1 sends real-time HTTP POST notifications to your configured webhook URL when authentication events occur. Configure webhooks in your Dashboard under Settings.

Events

• user.created Fired when a new user record is created during their first verification.
• user.verified Fired when a user successfully completes OTP or magic link verification.
• login.success Fired on every successful authentication (includes returning users).
• login.failed Fired when verification fails (wrong code, expired code, max attempts).
• fraud.detected Fired when a VOIP number is blocked or risk score exceeds your threshold.

Payload Format

{
  "id": "evt_a1b2c3d4e5f6",
  "event": "user.verified",
  "timestamp": "2026-03-23T14:30:00Z",
  "data": {
    "userId": "usr_abc123",
    "email": "user@example.com",
    "phone": "+18005551234",
    "method": "sms_otp",
    "riskScore": 0.12,
    "isVoip": false,
    "ip": "203.0.113.42"
  }
}

Signature Verification

Every webhook request includes an x-auth1-signature header containing an HMAC-SHA256 signature of the raw request body, signed with your auth1_sk_ secret key. Always verify this signature before processing.

import { createHmac } from 'crypto';

function verifyWebhook(body, signature, secret) {
  const expected = createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return expected === signature;
}

// In your Express handler:
app.post('/webhooks/auth1', (req, res) => {
  const sig = req.headers['x-auth1-signature'];
  if (!verifyWebhook(req.rawBody, sig, process.env.AUTH1_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  // Process the event...
  res.sendStatus(200);
});

VOIP Detection

Auth1 automatically classifies every phone number before sending an OTP. VOIP numbers (Google Voice, TextNow, Burner, etc.) are flagged in real-time, letting you block or challenge suspicious signups.

How It Works

• Every SMS request checks the phone number against carrier databases and proprietary heuristics.
• The phoneType field returns mobile, landline, or voip.
• The isVoip boolean provides a quick check for conditional logic.
• By default, VOIP numbers are allowed but flagged. Configure blocking rules in your Dashboard.

Configuration Options

Risk Scoring

Auth1 assigns a fraud risk score (0.0 to 1.0) to every authentication attempt. The score combines multiple signals in real-time.

Score Breakdown

Signals Used

• Phone type -- VOIP, prepaid, and landline numbers increase the score.
• Velocity -- Multiple attempts from the same IP or phone in a short window.
• Geolocation mismatch -- IP country vs. phone country code discrepancy.
• Known fraud patterns -- Number ranges and IPs associated with prior abuse across all Auth1 tenants.
• Device fingerprint -- Browser/device anomalies when using the client-side SDK.

Custom Branding

Personalize SMS messages, emails, and magic link pages with your company branding. Configure in the Dashboard or via the API.

SMS Templates

Customize the OTP message text. Use the {{code}} placeholder for the verification code and {{appName}} for your tenant's display name.

Your {{appName}} verification code is {{code}}. Expires in 10 minutes.

Email Branding

• Logo URL -- Displayed in the magic link email header.
• Primary color -- Applied to buttons and accents in the email template.
• From name -- The sender name shown in the user's inbox (e.g., "YourApp Security").
• Reply-to -- Where user replies go.

SDKs

Official client libraries for the most popular platforms. All SDKs include TypeScript definitions and handle retries, error mapping, and token refresh automatically.

Node.js Example

import Auth1 from '@auth1/sdk';

const auth = new Auth1({
  apiKey: process.env.AUTH1_API_KEY,
  tenant: 'your-tenant'
});

// Send OTP
const { phoneVerificationId, isVoip, riskScore } =
  await auth.sms.send({
    phone: '+18005551234',
    email: 'user@example.com'
  });

// Verify code
const session = await auth.sms.verify({
  phoneVerificationId,
  code: '123456',
  email: 'user@example.com'
});

console.log(session.token); // JWT access token

Python Example

from auth1 import Auth1Client

client = Auth1Client(
    api_key="auth1_pk_YOUR_KEY",
    tenant="your-tenant"
)

# Send OTP
result = client.sms.send(
    phone="+18005551234",
    email="user@example.com"
)

print(result.is_voip)      # False
print(result.risk_score)   # 0.12

# Verify code
session = client.sms.verify(
    phone_verification_id=result.phone_verification_id,
    code="123456",
    email="user@example.com"
)

React Example

import { Auth1Provider, VerifyForm, useAuth1 } from '@auth1/react';

function App() {
  return (
    <Auth1Provider apiKey="auth1_pk_...">
      <VerifyForm
        onSuccess={(session) => console.log('Verified!', session)}
        onVoipDetected={() => alert('VOIP numbers not allowed')}
      />
    </Auth1Provider>
  );
}

// Or use the hook directly:
function CustomLogin() {
  const { sendOTP, verifyCode, loading, session } = useAuth1();
  // Build your own UI...
}

Error Codes

All errors return a JSON body with error (machine-readable code) and message (human-readable description). HTTP status codes follow REST conventions.

{
  "error": "CODE_EXPIRED",
  "message": "Verification code has expired. Please request a new one.",
  "statusCode": 400
}

Rate Limits

Auth1 enforces rate limits to protect service quality and prevent abuse. Limits vary by endpoint and plan.

Rate Limit Headers

Every response includes rate limit headers so you can proactively manage your usage:

429 Response

When a rate limit is exceeded, you receive a 429 Too Many Requests response:

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please retry after 42 seconds.",
  "retryAfter": 42,
  "statusCode": 429
}