Device Management

Register and manage devices for push notification delivery. Zyphr tracks device tokens for iOS (APNs), Android (FCM), and Web Push, enabling targeted push delivery to specific devices or all of a user's devices.

Overview

Before sending push notifications, devices must be registered with Zyphr. Each device has a platform-specific token obtained from the push notification service (APNs, FCM, or Web Push).

Quick Start

Register a Device

curl -X POST https://api.zyphr.dev/v1/devices \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "platform": "ios",
    "token": "abc123def456...",
    "app_id": "com.yourapp.mobile"
  }'

await zyphr.devices.register({
  userId: 'user_123',
  platform: 'ios',
  token: 'abc123def456...',
  appId: 'com.yourapp.mobile',
});

Send a Push Notification

Once devices are registered, send push notifications by user ID — Zyphr delivers to all registered devices:

curl -X POST https://api.zyphr.dev/v1/push \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "title": "New Message",
    "body": "You have a new notification"
  }'

Registering Devices

Registration Parameters

Parameter	Type	Required	Description
user_id	string	Yes	Your application's user ID
platform	string	Yes	Device platform: ios, android, web
token	string	Yes	Platform-specific push token
app_id	string	No	Application bundle ID or package name
device_name	string	No	Human-readable device name
metadata	object	No	Custom metadata for the device

Platform-Specific Tokens

iOS (APNs)

Device tokens are obtained from UIApplication.shared.registerForRemoteNotifications():

func application(_ application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    let token = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()
    // Register with Zyphr
    registerDevice(userId: currentUser.id, platform: "ios", token: token)
}

Android (FCM)

Tokens are obtained from Firebase Cloud Messaging:

FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val token = task.result
        // Register with Zyphr
        registerDevice(userId = currentUser.id, platform = "android", token = token)
    }
}

Web Push

Use the Push API to get a subscription endpoint:

const registration = await navigator.serviceWorker.ready;
const subscription = await registration.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: vapidPublicKey,
});

// Register with Zyphr
await fetch('/api/register-device', {
  method: 'POST',
  body: JSON.stringify({
    userId: currentUser.id,
    platform: 'web',
    token: JSON.stringify(subscription),
  }),
});

Managing Devices

List Devices

curl "https://api.zyphr.dev/v1/devices?user_id=user_123&platform=ios&limit=25" \
  -H "X-API-Key: zy_live_your_api_key"

Query Parameters

Parameter	Type	Description
user_id	string	Filter by user ID
platform	string	Filter by platform: ios, android, web
limit	number	Results per page (default: 25, max: 100)
offset	number	Pagination offset

Get a Device

curl https://api.zyphr.dev/v1/devices/DEVICE_ID \
  -H "X-API-Key: zy_live_your_api_key"

Delete a Device

Remove a specific device (e.g., when a user logs out):

curl -X DELETE https://api.zyphr.dev/v1/devices/DEVICE_ID \
  -H "X-API-Key: zy_live_your_api_key"

await zyphr.devices.delete(deviceId);

Delete All User Devices

Remove all devices for a user (e.g., on account deletion):

curl -X DELETE https://api.zyphr.dev/v1/devices/user/user_123 \
  -H "X-API-Key: zy_live_your_api_key"

await zyphr.devices.deleteByUser('user_123');

Device Statistics

Get aggregated device statistics for your workspace:

curl https://api.zyphr.dev/v1/devices/stats \
  -H "X-API-Key: zy_live_your_api_key"

Returns:

• Total registered devices
• Breakdown by platform (iOS, Android, Web)
• Active vs. stale device counts

Token Refresh

Push tokens can change over time. When your app receives a new token, re-register the device:

// On token refresh (called by FCM/APNs)
async function onTokenRefresh(newToken: string) {
  await zyphr.devices.register({
    userId: currentUser.id,
    platform: 'android',
    token: newToken,
    appId: 'com.yourapp.mobile',
  });
}

Zyphr deduplicates by user_id + platform + token, so re-registering with the same token is a no-op.

Best Practices

• Register on every app launch - Tokens can change, so always register the current token
• Clean up on logout - Delete the device when a user signs out to prevent stale deliveries
• Handle token expiry - If a push delivery returns an invalid token error, the device is automatically marked as inactive
• Use app_id - When you have multiple apps, use app_id to distinguish device registrations

API Reference

Method	Endpoint	Scopes	Description
POST	/v1/devices	push:write	Register a device
GET	/v1/devices	push:read	List devices
GET	/v1/devices/stats	push:read	Get device statistics
GET	/v1/devices/:id	push:read	Get a device
DELETE	/v1/devices/:id	push:write	Delete a device
DELETE	/v1/devices/user/:user_id	push:write	Delete all user devices

Next Steps

• Push Notifications - Send push notifications to registered devices
• Subscribers - Map devices to subscriber profiles
• In-App Messaging - Add an in-app notification center