Device Token Registration

Overview

To receive mobile push notifications, an authenticated tenant user can register a device token with the Survanta server. Client applications are responsible for obtaining the token from their notification provider and calling the registration endpoint; the backend does not make this automatic.

What Is a Device Token?

A device token is the provider-issued destination identifier supplied by the mobile client. Survanta stores one current token on the user account. Registering another token replaces the previously stored value.

How Registration Works

The current server contract is:

1. Sign in through POST /api/mobile/auth/login and retain the JWT.
2. Obtain the provider token after notification permission is granted.
3. Call POST /api/Researcher/device-token with Authorization: Bearer <jwt> and JSON body { "deviceToken": "...", "deviceType": "..." }.
4. The caller must satisfy the mobile tenant-user policy and Tenant.ReceiveMobileNotifications permission.
5. deviceType is accepted by the request contract but is not currently persisted or used by the service.

Keeping Your Token Up to Date

Device tokens can change in certain situations:

• When you uninstall and reinstall the app.
• When the operating system refreshes the token (this can happen periodically on iOS and Android).
• When you sign in from a different device.

The mobile client must detect token rotation and call the registration endpoint again. Survanta replaces the token stored for the current user.

Multiple Devices

The current data model stores one device token per user, not a collection of device registrations. Registering from a second device replaces the first device's token, so simultaneous multi-device push delivery is not supported by this contract.

Notification Permission Required

Notification permission is managed by the device and notification provider, not by the Survanta endpoint. If permission was denied:

1. Go to your device Settings.
2. Find Survanta in the app list.
3. Enable Notifications.
4. Re-open the client, obtain a provider token, and submit it through the registration endpoint.

Privacy

• Your device token is used solely for delivering Survanta push notifications to your device.
• Treat the token as sensitive routing data and do not log or expose it unnecessarily.
• Signing out does not remove it automatically. Before discarding the JWT, the client can call DELETE /api/Researcher/device-token with the same authorization and a non-empty deviceToken request value; the service clears the current user's stored token.

Troubleshooting

• Not receiving push notifications: Confirm permission, obtain a current provider token, and call the registration endpoint with a valid JWT and the required permission.
• A second device stopped the first device receiving notifications: This is expected because only one token is stored per user.
• Push notifications stopped after a device update: Obtain the refreshed provider token and register it again.