DeviceCheck API Demo

A tutorial project demonstrating Apple's DeviceCheck API for device-based banning. This allows you to ban devices (not just accounts) so even if a banned user creates a new account, they cannot access your service.

How It Works

iOS App                    Your Server                 Apple Server
   │                           │                            │
   │ 1. Generate device token  │                            │
   │ ─────────────────────────>│                            │
   │                           │ 2. Query/Update bits       │
   │                           │ ──────────────────────────>│
   │                           │                            │
   │                           │ 3. Return bit values       │
   │                           │ <──────────────────────────│
   │ 4. Banned/Not banned      │                            │
   │ <─────────────────────────│                            │

Apple stores 2 bits per device that persist even if the app is deleted:

• bit0: We use this for "is banned" (true = banned)
• bit1: Reserved for future use

Project Structure

DeviceCheck/
├── DeviceCheckProj/          # iOS SwiftUI App
│   └── DeviceCheckProj/
│       ├── ContentView.swift          # Demo UI
│       ├── DeviceCheckService.swift   # DCDevice wrapper
│       └── APIService.swift           # Network client
│
└── server/                   # Node.js Backend
    ├── src/
    │   ├── index.js                   # Express server
    │   ├── config/database.js         # MySQL connection
    │   ├── routes/deviceCheck.js      # API endpoints
    │   ├── services/appleDeviceCheck.js  # Apple API
    │   └── utils/jwt.js               # JWT generation
    └── sql/schema.sql                 # Database schema

Prerequisites

• macOS with Xcode 15+
• Node.js 18+
• MySQL 8.0+
• Apple Developer Account with DeviceCheck capability

Setup

1. Get DeviceCheck Key from Apple

1. Go to App Store Connect
2. Navigate to Users and Access > Integrations > Keys
3. Click Generate API Key or use the "DeviceCheck" section
4. Download the .p8 file (you can only download it once!)
5. Note your Team ID and Key ID

2. Setup MySQL Database

# Start MySQL if not running
mysql.server start

# Create the database and tables
mysql -u root -p < server/sql/schema.sql

3. Configure the Server

cd server

# Copy environment template
cp .env.example .env

# Edit .env with your values:
# - APPLE_TEAM_ID: Your team ID from App Store Connect
# - APPLE_KEY_ID: Your key ID from the .p8 file name
# - APPLE_PRIVATE_KEY_PATH: Path to your .p8 file
# - DB_PASSWORD: Your MySQL password

# Install dependencies
npm install

# Start the server
npm run dev

4. Configure the iOS App

• If testing on a real device, update the server URL in APIService.swift:

  private let baseURL = "http://YOUR_MAC_IP:3000/api"

• Build and run on a real device (DeviceCheck doesn't work on simulator)

API Endpoints

Endpoint	Method	Description
/api/check-device	POST	Check if a device is banned
/api/ban-device	POST	Ban a device
/api/unban-device	POST	Unban a device
/api/register	POST	Simulate registration (fails if banned)
/health	GET	Health check

Example Requests

# Check device status
curl -X POST http://localhost:3000/api/check-device \
  -H "Content-Type: application/json" \
  -d '{"deviceToken": "BASE64_TOKEN_HERE"}'

# Ban a device
curl -X POST http://localhost:3000/api/ban-device \
  -H "Content-Type: application/json" \
  -d '{"deviceToken": "BASE64_TOKEN_HERE", "reason": "Fraudulent activity"}'

# Simulate registration
curl -X POST http://localhost:3000/api/register \
  -H "Content-Type: application/json" \
  -d '{"deviceToken": "BASE64_TOKEN_HERE", "username": "newuser123"}'

Important Notes

• DeviceCheck only works on real devices, not simulators
• Device tokens are ephemeral (temporary) - generate a new one for each request
• Use api.development.devicecheck.apple.com for testing
• Use api.devicecheck.apple.com for production