Authentication Methods

WhatsApp API supports two authentication methods: QR Code scanning and Pairing Code.

QR Code Authentication (Default)

The traditional method of linking WhatsApp by scanning a QR code.

Get QR Code

GET /sessions/{id}/qr

See Session Management for full documentation.

How It Works

1. Create a session
2. Get QR code from /sessions/{id}/qr
3. Open WhatsApp on your phone
4. Go to Settings → Linked Devices → Link a Device
5. Scan the QR code
6. Session state changes to ready

---

Pairing Code Authentication (NEW)

Alternative authentication method using an 8-digit code instead of QR scanning.

Request Pairing Code

Get an 8-digit pairing code to link WhatsApp without scanning QR.

POST /sessions/{id}/auth/request-code

Headers

Header	Value
X-API-Key	Your session API key

Request Body

Parameter	Type	Required	Description
phoneNumber	string	Yes	Phone number with country code (no + or spaces)

Example Request

curl -X POST http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/auth/request-code \
  -H "X-API-Key: wask_your_session_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "919988066776"
  }'

Response

{
  "success": true,
  "code": "12345678",
  "phoneNumber": "919988066776",
  "message": "Enter this code in WhatsApp > Linked Devices > Link a Device > Link with phone number"
}

How It Works

1. Create a session
2. Request pairing code with your phone number
3. Open WhatsApp on your phone
4. Go to Settings → Linked Devices → Link a Device
5. Tap Link with phone number instead
6. Enter the 8-digit code
7. Session state changes to ready

Phone Number Format

Format	Valid	Example
With country code	✅	919988066776
With + prefix	❌	+919988066776
With spaces	❌	91 998 806 6776
With dashes	❌	91-998-806-6776
Without country code	❌	9988066776

Best Practice

Always include the country code without any special characters.

---

Comparison: QR Code vs Pairing Code

Feature	QR Code	Pairing Code
Ease of Use	Scan with camera	Enter 8 digits
Automation	Requires image display	Easier to automate
Headless Servers	Difficult	Easy
User Experience	Visual	Text-based
Security	Same	Same
Expiration	~60 seconds	~60 seconds

---

When to Use Each Method

Use QR Code When:

• Running on a local machine with display
• User has easy camera access
• Building a desktop application
• User prefers visual authentication

Use Pairing Code When:

• Running on headless servers
• Building automation tools
• Camera access is difficult
• User prefers typing over scanning
• Building CLI applications

---

Error Responses

Already Authenticated

{
  "success": false,
  "error": "Already authenticated"
}

Solution: Session is already linked. No need to authenticate again.

Invalid Phone Number

{
  "success": false,
  "error": "Invalid phone number format"
}

Solution: Ensure phone number includes country code and has no special characters.

Session Not Found

{
  "success": false,
  "error": "Session not found or not started"
}

Solution: Ensure session is created and started before requesting pairing code.

---

Code Examples

JavaScript (Node.js)

const axios = require('axios');

async function authenticateWithPairingCode(sessionId, phoneNumber) {
  try {
    const response = await axios.post(
      `http://localhost:3000/sessions/${sessionId}/auth/request-code`,
      { phoneNumber },
      {
        headers: {
          'X-API-Key': 'wask_your_session_key',
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log('Pairing Code:', response.data.code);
    console.log('Instructions:', response.data.message);
    
    return response.data.code;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

// Usage
authenticateWithPairingCode('e67a00be-ed45-4356-9488-049cabb9895d', '919988066776');

Python

import requests

def authenticate_with_pairing_code(session_id, phone_number):
    url = f"http://localhost:3000/sessions/{session_id}/auth/request-code"
    headers = {
        "X-API-Key": "wask_your_session_key",
        "Content-Type": "application/json"
    }
    data = {"phoneNumber": phone_number}
    
    response = requests.post(url, json=data, headers=headers)
    result = response.json()
    
    if result.get("success"):
        print(f"Pairing Code: {result['code']}")
        print(f"Instructions: {result['message']}")
        return result['code']
    else:
        print(f"Error: {result.get('error')}")

# Usage
authenticate_with_pairing_code('e67a00be-ed45-4356-9488-049cabb9895d', '919988066776')

cURL

# Request pairing code
curl -X POST http://localhost:3000/sessions/SESSION_ID/auth/request-code \
  -H "X-API-Key: wask_your_session_key" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "919988066776"}'

# Check session status
curl -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/SESSION_ID/status

---

Security Considerations

1. Code Expiration: Pairing codes expire after ~60 seconds
2. One-Time Use: Each code can only be used once
3. Rate Limiting: Limited requests to prevent abuse
4. API Key Required: Must have valid session API key
5. HTTPS Recommended: Use HTTPS in production

Important

Never share your pairing code or API key publicly. Treat them like passwords.