Zauthy Documentation

// Request
{
  "email": "user@example.com",
  "password": "SecureP@ss123",
  "name": "Jane Doe",           // optional
  "phone": "+1234567890"        // optional
}

// Response 201
{
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "Jane Doe",
    "role": "user",
    "is_verified": false,
    "created_at": "2026-03-07T10:00:00Z"
  },
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 900
}

// Request
{
  "email": "user@example.com",
  "password": "SecureP@ss123"
}

// Response 200
{
  "user": { "id": "usr_abc123", "email": "user@example.com", "role": "user", ... },
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 900,
  "mfa_required": false     // true if user has MFA enabled
}

// Response 200 (MFA required)
{
  "mfa_required": true,
  "mfa_token": "mfa_tmp_...",
  "mfa_methods": ["totp"]
}

// Request
{ "refresh_token": "eyJ..." }

// Response 200
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",  // rotated
  "token_type": "bearer",
  "expires_in": 900
}

// Response 200
{ "success": true }

// Request
{ "token": "eyJ..." }

// Response 200
{
  "valid": true,
  "user_id": "usr_abc123",
  "role": "user",
  "org_id": "org_xyz789",
  "expires_at": "2026-03-07T10:15:00Z"
}

// Request
{ "email": "user@example.com" }

// Response 200 (always succeeds to prevent email enumeration)
{ "message": "If an account exists, a reset link has been sent." }

// Request
{ "token": "reset_token_...", "new_password": "NewSecureP@ss123" }

// Request
{
  "email": "user@example.com",
  "redirect_url": "https://yourapp.com/auth/callback"  // optional
}

// Request
{ "token": "magic_token_..." }

// Response 200
{
  "user": { ... },
  "access_token": "eyJ...",
  "refresh_token": "eyJ..."
}

// Request
{
  "email": "user@example.com",    // or "phone": "+1234567890"
  "channel": "email"              // "email" or "sms"
}

// Request
{
  "email": "user@example.com",
  "code": "123456"
}

// Response 200
{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_uri": "otpauth://totp/Zauthy:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Zauthy",
  "backup_codes": ["abc123", "def456", ...]
}

// Request
{
  "code": "123456",
  "mfa_token": "mfa_tmp_..."  // from login response
}

// Request
{
  "provider": "google",
  "redirect_url": "https://yourapp.com/auth/callback"
}

// Response 200
{ "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?..." }

// Request
{
  "user_id": "usr_abc123",             // optional, link to existing user
  "type": "full_kyc",                  // "full_kyc" | "document_only" | "face_only"
  "checks": ["document", "face", "liveness"],
  "metadata": { "source": "onboarding" }
}

// Response 201
{
  "id": "kyc_sess_abc123",
  "status": "pending",
  "checks": ["document", "face", "liveness"],
  "created_at": "2026-03-07T10:00:00Z",
  "expires_at": "2026-03-07T11:00:00Z"
}

curl -X POST https://api.zauthy.com/v1/kyc/sessions/{session_id}/documents \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@passport.jpg" \
  -F "document_type=passport" \
  -F "country=US"

# Response 200
{
  "document_id": "doc_abc123",
  "status": "processed",
  "document_type": "passport",
  "extracted_data": {
    "full_name": "Jane Doe",
    "date_of_birth": "1990-01-15",
    "document_number": "AB1234567",
    "expiry_date": "2030-01-15",
    "country": "US"
  },
  "confidence": 0.97
}

// Response 200
{
  "match": true,
  "confidence": 0.94,
  "threshold": 0.80
}

// Response 200
{
  "is_live": true,
  "confidence": 0.98,
  "checks": {
    "texture_analysis": true,
    "depth_estimation": true,
    "blink_detection": true
  }
}

// Request
{
  "latitude": 37.7749,
  "longitude": -122.4194,
  "accuracy": 10.0
}

// Request
{
  "url": "https://yourapp.com/webhooks/zauthy",
  "events": ["user.signup", "kyc.completed", "kyc.failed"],
  "active": true
}

// Response 201
{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/zauthy",
  "secret": "whsec_...",  // for signature verification
  "events": ["user.signup", "kyc.completed", "kyc.failed"],
  "active": true
}

// Request
{
  "email": "user@example.com",
  "ip": "203.0.113.42",
  "device_fingerprint": "fp_...",
  "user_agent": "Mozilla/5.0..."
}

// Response 200
{
  "risk_score": 0.15,       // 0.0 (safe) to 1.0 (high risk)
  "risk_level": "low",      // "low" | "medium" | "high"
  "flags": [],              // ["new_device", "impossible_travel", "tor_exit_node"]
  "recommendation": "allow" // "allow" | "mfa" | "block"
}

// Request
{ "ip": "203.0.113.42" }

// Response 200
{
  "ip": "203.0.113.42",
  "is_vpn": false,
  "is_proxy": false,
  "is_tor": false,
  "is_datacenter": false,
  "country": "US",
  "city": "San Francisco",
  "risk_score": 0.05
}