Devices

Devices in Bouncer represent physical or virtual verification points such as kiosks, vending machines, point-of-sale systems, or tablets.

Overview

Devices provide a simplified verification flow:

Device displays a QR code
User scans the code with their phone
Verification happens on the user's device
Result is sent back to the device

Creating a Device

Via Dashboard

Log in to your Bouncer dashboard
Navigate to Devices
Click Add Device
Configure the device settings:
- Name: A descriptive name (e.g., "Store Front Kiosk #1")
- Age Target: Default age to verify
- Redirect URL: Where users go after verification
- Webhook URL: Endpoint for verification events
- Force KYC: Always require ID verification
- Expiration Time: Session timeout in seconds

Device Code

Each device receives a unique code (e.g., ABC123) used for:

Direct verification URLs: /d/{deviceCode}
Dynamic session URLs via API

Device Verification Flows

Direct URL Flow

For static QR codes printed on devices:

https://your-bouncer-instance.com/d/ABC123

When scanned:

Creates a new session with device settings
Cancels any incomplete sessions for this device
Redirects to verification page

Dynamic URL Flow

For devices that display dynamic QR codes:

# Generate a new session URL
curl -X POST https://your-bouncer-instance.com/api/v2/device/ABC123/session-url \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "qr_size": 400,
    "ttl": 300
  }'

Response:

{
  "url": "https://your-bouncer-instance.com/s/XyZ12AbC",
  "qr": "data:image/png;base64,iVBORw0KGgo...",
  "expires_at": "2024-01-15T10:35:00Z"
}

Display the QR code on your device screen. The short URL expires after the TTL.

Device Configuration

Settings

Setting	Description	Default
`name`	Device identifier	Required
`device_code`	Unique code (auto-generated)	Auto
`age_target`	Age to verify	Organization default
`redirect_url`	Post-verification URL	Required
`webhook_url`	Event notification URL	Optional
`force_kyc`	Always require ID scan	false
`expiration_time`	Session TTL (seconds)	300
`is_active`	Enable/disable device	true

Example Device Flow

// Kiosk Application

class VerificationKiosk {
  constructor(apiToken, deviceCode) {
    this.apiToken = apiToken;
    this.deviceCode = deviceCode;
    this.currentSession = null;
  }

  async displayNewQR() {
    const response = await fetch(
      `https://bouncer.example.com/api/v2/device/${this.deviceCode}/session-url`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.apiToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          qr_size: 500,
          ttl: 300
        })
      }
    );

    const data = await response.json();

    // Display QR on screen
    this.showQRCode(data.qr);

    // Set up auto-refresh before expiration
    setTimeout(() => this.displayNewQR(), 280000); // Refresh at 4:40
  }

  showQRCode(base64Image) {
    document.getElementById('qr-display').src = base64Image;
  }
}

// Initialize kiosk
const kiosk = new VerificationKiosk('YOUR_TOKEN', 'ABC123');
kiosk.displayNewQR();

Webhook Integration

Configure webhooks to receive real-time verification results:

// Express.js webhook handler
app.post('/webhooks/device/:deviceCode', (req, res) => {
  const { deviceCode } = req.params;
  const { session_id, success, status } = req.body;

  if (success) {
    // User verified - unlock content, dispense product, etc.
    deviceController.onVerificationSuccess(deviceCode, session_id);
  } else {
    // Verification failed
    deviceController.onVerificationFailed(deviceCode, session_id);
  }

  res.status(200).send('OK');
});

Device Branding

Devices inherit your organization's branding:

Logo: Displayed on verification page
Primary Color: UI accent color
Secondary Color: Background color

Customize branding in Settings > Organization > Branding.

Use Cases

Vending Machines

User approaches vending machine
    ↓
Selects age-restricted item
    ↓
QR code displayed on screen
    ↓
User scans, completes verification on phone
    ↓
Webhook notifies machine
    ↓
Item dispensed

Point of Sale

Cashier initiates age check
    ↓
Customer tablet shows QR code
    ↓
Customer scans with their phone
    ↓
Verification completes
    ↓
POS system updated via webhook
    ↓
Transaction proceeds

Event Entry

Guest arrives at venue
    ↓
Scans QR code at gate
    ↓
Completes verification on phone
    ↓
Gate system receives webhook
    ↓
Access granted

Device Management

Activating/Deactivating

Devices can be temporarily disabled without deleting:

Go to Devices
Find the device
Toggle Active status

Inactive devices cannot create new sessions.

Monitoring

View device statistics:

Total verifications
Success rate
Average completion time
Recent activity

Device Events

Each verification creates events:

session_created
page_visited
biometry_started
kyc_started (if applicable)
completed

Best Practices

Use meaningful names: "Main Entrance Gate" not "Device 1"
Set appropriate timeouts: Longer for complex flows, shorter for quick checks
Monitor webhook delivery: Ensure your endpoint is reliable
Implement fallbacks: Handle cases when Bouncer is unreachable
Secure your devices: Protect API tokens on physical devices

Devices

On this page