Passwordless Authentication

ShopSynch.4/6/26About 1 min

Passwordless Authentication

Description

ShopSynch offers a Passwordless Authentication mode, allowing users to log in securely without needing to remember or enter a password. This is achieved via Email Magic Links or WhatsApp OTPs.

Passwordless authentication is available for both Merchants and Customers.

🚀 Step 1: Initiate Authentication

The first step is to request a login link or verification code.

1. Unified Initiation

Initiate both email and phone (WhatsApp) authentication simultaneously.

Endpoint: POST /v1/auth/passwordless/initiate
Request Body:

{
  "email": "user@example.com",
  "phoneNumber": "+2348000000000",
  "userType": "MERCHANT", // or "CUSTOMER"
  "businessName": "My Store" // Optional for new merchants
}

2. Email-Only Initiation

Request a login link sent directly to the user's email.

Endpoint: POST /v1/auth/passwordless/initiate/email
Request Body:

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

3. Phone-Only Initiation

Request a verification code (OTP) sent via WhatsApp.

Endpoint: POST /v1/auth/passwordless/initiate/phone
Request Body:

{
  "phoneNumber": "+2348000000000"
}

Once the user receives the link or code, they must verify it to complete the login process.

For Merchants

Verify Email (Magic Link)

When the merchant clicks the link in their email, your application should extract the token and call this endpoint.

Endpoint: POST /v1/auth/passwordless/merchant/verify-email
Request Body:

{
  "email": "merchant@example.com",
  "token": "MAGIC_LINK_TOKEN"
}

Verify Phone (WhatsApp OTP)

The merchant enters the 6-digit code received on WhatsApp.

Endpoint: POST /v1/auth/passwordless/merchant/verify-phone
Request Body:

{
  "phoneNumber": "+2348000000000",
  "code": "123456"
}

For Customers

Verify Email (Magic Link)

Endpoint: POST /v1/auth/passwordless/customer/verify-email
Required Headers: X-Session-Id (Optional, for cart migration)
Request Body:

{
  "email": "customer@example.com",
  "token": "MAGIC_LINK_TOKEN"
}

Verify Phone (WhatsApp OTP)

Endpoint: POST /v1/auth/passwordless/customer/verify-phone
Required Headers: X-Session-Id (Optional, for cart migration)
Request Body:

{
  "phoneNumber": "+2348000000000",
  "code": "123456"
}

📥 Response Structure

Upon successful verification, the API returns the user's profile and JWT session tokens.

✅ Sample 200 Response (Success)

{
    "status": true,
    "message": "Email verified successfully.",
    "data": {
        "user": {
            "id": "67e81c4b752..." ,
            "email": "user@example.com",
            "fullName": "John Doe",
            "role": "customer"
        },
        "token": "eyJhbGciOiJIUzUxMiJ9...",
        "refreshToken": "7c8d9e...",
        "expiresIn": 86400000
    }
}