# Baileys Authentication Methods: QR Code vs Pairing Code Explained

> Explore Baileys authentication: QR code for multi-device, pairing code for headless, and saved auth for seamless reconnections. Understand your options.

- Repository: [WhiskeySockets/Baileys](https://github.com/WhiskeySockets/Baileys)
- Tags: deep-dive
- Published: 2026-08-01

---

**Baileys supports three authentication methods: QR code scanning for multi-device sessions, pairing code entry for single-device headless setups, and saved auth state for automatic reconnections without user interaction.**

Baileys, the popular open-source WhatsApp Web API for Node.js by WhiskeySockets, implements the official WhatsApp Web multi-device protocol to authenticate clients. Understanding the differences between **QR code** and **pairing code** authentication is essential for choosing the right approach for your deployment environment.

---

## QR Code Authentication (Multi-Device)

The **QR code method** is the default authentication flow in Baileys. It establishes a **multi-device session**, allowing the same WhatsApp account to run simultaneously across multiple Baileys instances and official WhatsApp Web clients.

### How It Works

When `makeWASocket()` initializes, Baileys opens a WebSocket connection to WhatsApp's servers. Upon receiving a `<pair-device>` stanza, it generates a QR code containing the pairing key. The user scans this code with the WhatsApp mobile app, which encrypts and transmits the session keys back to Baileys.

The QR generation logic resides in [`src/Socket/socket.ts`](https://github.com/WhiskeySockets/Baileys/blob/main/src/Socket/socket.ts) at lines 71-99, where the library constructs the pairing payload and formats it for display:

```typescript
// QR-code authentication (default multi-device)
import makeWASocket, { useMultiFileAuthState, Browsers } from '@whiskeysockets/baileys';

const { state, saveCreds } = await useMultiFileAuthState('baileys_auth');

const sock = makeWASocket({
  auth: state,
  browser: Browsers.ubuntu('My Bot'),  // Custom browser fingerprint
  printQRInTerminal: true,              // Auto-print QR (deprecated)
});

sock.ev.on('creds.update', saveCreds);

sock.ev.on('connection.update', ({ qr }) => {
  if (qr) console.log('QR received:', qr);
});

```

**Key characteristics:**

- **Device model**: Multi-device (concurrent sessions supported)
- **User interaction**: Visual scan of QR code from mobile app
- **Typical use case**: Development, production services requiring multiple connections

> **Note**: The `printQRInTerminal` option is now deprecated. Implement custom QR handlers via the `connection.update` event for production applications.

---

## Pairing Code Authentication (Single-Device)

The **pairing code method** provides an alternative for environments where QR scanning is impractical. It creates a **single-device session**, meaning this Baileys instance becomes the exclusive WhatsApp Web connection for the account.

### Implementation in socket.ts

The `requestPairingCode()` method, implemented at lines 64-71 of [`src/Socket/socket.ts`](https://github.com/WhiskeySockets/Baileys/blob/main/src/Socket/socket.ts), requests an 8-character alphanumeric code from WhatsApp servers:

```typescript
// Pairing code authentication (single-device, headless-friendly)
import makeWASocket, { useMultiFileAuthState } from '@whiskeysockets/baileys';

const { state, saveCreds } = await useMultiFileAuthState('baileys_auth');

const sock = makeWASocket({
  auth: state,
  printQRInTerminal: false,  // Disable QR generation
});

sock.ev.on('creds.update', saveCreds);

// Request pairing code for unregistered sessions
if (!sock.authState.creds.registered) {
  const phoneNumber = '15551234567';  // Format: country code + number, no '+'
  const pairingCode = await sock.requestPairingCode(phoneNumber);
  
  console.log(`Enter this code in WhatsApp → Linked Devices → Link with phone number: ${pairingCode}`);
}

```

**Key characteristics:**

- **Device model**: Single-device (exclusive session, no concurrent connections)
- **User interaction**: Manual 8-character code entry in WhatsApp mobile app
- **Typical use case**: Headless servers, automated deployments, environments without display access

After the user enters the code, Baileys transmits the pairing key via `sendNode` to complete authentication.

---

## Saved Authentication State

Both QR and pairing code methods support **credential persistence** through `useMultiFileAuthState`, located in [`src/Utils/use-multi-file-auth-state.ts`](https://github.com/WhiskeySockets/Baileys/blob/main/src/Utils/use-multi-file-auth-state.ts). This eliminates repeated authentication after initial setup.

```typescript
// Reconnect using saved credentials (no QR or pairing needed)
import makeWASocket, { useMultiFileAuthState } from '@whiskeysockets/baileys';

const { state, saveCreds } = await useMultiFileAuthState('baileys_auth');

const sock = makeWASocket({
  auth: state,  // Automatically loads existing credentials
});

sock.ev.on('creds.update', saveCreds);

sock.ev.on('connection.update', ({ connection }) => {
  if (connection === 'open') {
    console.log('Reconnected using saved auth state');
  }
});

```

The auth state includes:

- `authState.creds` — Session credentials and encryption keys
- `authState.keys` — Pre-key bundles for the Signal protocol

This pattern is **recommended for all production deployments** to ensure reliable reconnections without manual intervention.

---

## Key Differences Summary

| Aspect | QR Code | Pairing Code |
|--------|---------|--------------|
| **Device support** | Multi-device | Single-device only |
| **Session exclusivity** | Concurrent sessions allowed | Exclusive connection |
| **User interaction** | Scan visual QR code | Type 8-character code |
| **Environment** | Development, desktop | Headless, automated |
| **Implementation location** | [`socket.ts`](https://github.com/WhiskeySockets/Baileys/blob/main/socket.ts) lines 71-99 | [`socket.ts`](https://github.com/WhiskeySockets/Baileys/blob/main/socket.ts) lines 64-71 |
| **Primary method** | Default, recommended | Alternative for edge cases |

---

## Configuration Options

Authentication behavior is controlled through the **SocketConfig** interface in [`src/Types/Socket.ts`](https://github.com/WhiskeySockets/Baileys/blob/main/src/Types/Socket.ts):

- `auth` — Required. Auth state from `useMultiFileAuthState` or custom implementation
- `printQRInTerminal` — Deprecated. Controls legacy QR auto-printing
- `browser` — Optional. Customizes the browser fingerprint sent to WhatsApp

---

## Summary

- **QR code authentication** is the standard method for multi-device sessions, implemented in [`src/Socket/socket.ts`](https://github.com/WhiskeySockets/Baileys/blob/main/src/Socket/socket.ts) with support for concurrent connections across multiple clients.
- **Pairing code authentication** enables headless single-device setup via `requestPairingCode()`, useful when visual QR scanning is unavailable.
- **Saved auth state** via `useMultiFileAuthState` provides seamless reconnection for both methods without repeated user authentication.
- **Architecture choice** — Multi-device (QR) for flexibility, single-device (pairing code) for exclusive control or constrained environments.

---

## Frequently Asked Questions

### Can I switch from pairing code to QR code authentication later?

Yes. Delete the existing auth state directory and reinitialize with `makeWASocket()` using default settings. The next connection will trigger QR code generation, establishing a new multi-device session. Existing single-device sessions will be terminated.

### Why is my pairing code request failing with "registered" error?

The `requestPairingCode()` method only works when `sock.authState.creds.registered` is `false`. If credentials already exist, Baileys attempts automatic reconnection instead. Clear the auth state directory to force a fresh pairing code request.

### How long do saved credentials remain valid?

According to the WhatsApp Web protocol implementation in Baileys, credentials persist until the user manually logs out from the mobile app or disconnects the device from Linked Devices. The library handles key rotation automatically via the `creds.update` event.

### Does Baileys support authentication without any user interaction?

No. Both methods require the WhatsApp account owner to complete authentication through the mobile app—either by scanning a QR code or entering a pairing code. Saved auth state eliminates *repeated* interaction, but initial setup always requires user confirmation for security.