Vaultwarden Push Notification Support: Configuration and Implementation Guide

Vaultwarden supports mobile-client push notifications through the Bitwarden push relay service, enabling real-time sync for cipher changes, authentication requests, and session events by setting PUSH_ENABLED=true with valid installation credentials.

The dani-garcia/vaultwarden repository implements mobile push notification support that mirrors the official Bitwarden Web Vault’s real-time update capabilities. This feature allows self-hosted instances to deliver instant notifications to mobile devices for password changes, folder updates, and security events without requiring persistent WebSocket connections. Understanding how to configure and leverage this push infrastructure ensures your mobile clients stay synchronized with server state.

How Push Notifications Work in Vaultwarden

Vaultwarden’s push system integrates with the official Bitwarden push relay (https://push.bitwarden.com) to deliver messages to mobile clients using Firebase Cloud Messaging (FCM) or Apple Push Notification service (APNs) tokens. When enabled, the server authenticates against Bitwarden’s identity service using OAuth2 credentials before dispatching notifications.

Core Architecture and Data Flow

The implementation spans three primary source files:

• src/api/push.rs – Handles low-level device registration and relay communication
• src/api/notifications.rs – Dispatches high-level events to the push subsystem
• src/db/models/device.rs – Persists device tokens and unique identifiers

The operational flow follows these steps:

1. Configuration validation – On startup, src/config.rs verifies that PUSH_ENABLED is accompanied by valid PUSH_INSTALLATION_ID and PUSH_INSTALLATION_KEY values (lines 998–1009).
2. Device registration – Mobile clients submit push tokens to the /identity/register endpoint, which stores the token alongside a generated push_uuid in the devices table.
3. Event triggering – When users modify ciphers, folders, or authentication states, src/api/notifications.rs invokes specialized helpers like push_cipher_update() or push_logout().
4. Relay dispatch – The system constructs JSON payloads containing deviceId, pushToken, and installationId, then POSTs them to the push relay URI.

If push notifications are disabled, Vaultwarden automatically falls back to WebSocket notifications when WEBSOCKET_ENABLED is true; otherwise, real-time updates are disabled entirely.

Supported Push Notification Events

Vaultwarden’s push subsystem supports a comprehensive range of real-time events defined in src/api/push.rs and invoked from src/api/notifications.rs:

• Cipher modifications – Creation, updates, and deletion of password entries trigger immediate mobile sync.
• Folder changes – Organizational folder creation, renaming, or deletion events.
• Session management – Remote logout commands that terminate other active sessions.
• Authentication requests – Passwordless login approval requests and corresponding responses.
• Send objects – Creation or modification of Bitwarden Send items for secure sharing.

Each event type utilizes specific helper functions (e.g., push_cipher_update(), push_auth_request()) that prepare contextual payloads before delegating to the core send_to_push_relay() function.

Configuration Options and Environment Variables

All push-related settings are defined in src/config.rs and documented in .env.template. Configure these variables in your server environment or Docker Compose file:

• PUSH_ENABLED – Boolean flag that activates the entire push subsystem. Defaults to false.
• PUSH_INSTALLATION_ID – UUID obtained from the Bitwarden host portal identifying your server instance. Required when push is enabled.
• PUSH_INSTALLATION_KEY – Secret key paired with the installation ID for OAuth2 authentication against the identity service. Required when push is enabled.
• PUSH_RELAY_URI – Base URL of the push relay endpoint. Defaults to https://push.bitwarden.com.
• PUSH_IDENTITY_URI – URL of the token issuance service. Defaults to https://identity.bitwarden.com.

Critical requirement: When PUSH_ENABLED is set to true, both PUSH_INSTALLATION_ID and PUSH_INSTALLATION_KEY must contain valid values. The server logs a startup error and aborts push operations if either credential is missing.

Step-by-Step Configuration Guide

Enable Vaultwarden push notifications by completing the following steps:

1. Obtain Bitwarden host credentials – Visit the Bitwarden web portal and navigate to Settings → Mobile client → Push notifications to generate an Installation ID and Installation Key for your self-hosted instance.

2. Configure environment variables – Add the following to your .env file or Docker environment:

   PUSH_ENABLED=true
   PUSH_INSTALLATION_ID=12345678-90ab-cdef-1234-567890abcdef
   PUSH_INSTALLATION_KEY=abcdefghijklmnopqrstuvwxyz1234567890
   
   # Optional: only modify if using custom relay services
   
   # PUSH_RELAY_URI=https://push.bitwarden.com
   
   # PUSH_IDENTITY_URI=https://identity.bitwarden.com
   

3. Restart the server – Reload your Vaultwarden container or service. Check startup logs for confirmation that push initialization succeeded.

4. Register mobile devices – Install the official Bitwarden mobile application, sign in to your Vaultwarden instance, and accept push notification permissions. The app automatically calls the /identity/register endpoint, persisting the FCM or APNs token in the database via src/db/models/device.rs.

Once registered, any supported event generates instant notifications on the registered mobile device.

Technical Implementation Details

Device Registration Flow

The register_push_device() function in src/api/push.rs manages the initial handshake with the Bitwarden relay:

// src/api/push.rs
pub async fn register_push_device(device: &mut Device, conn: &DbConn) -> EmptyResult {
    if !CONFIG.push_enabled() || !device.is_push_device() {
        return Ok(());  // Early exit if push disabled or device unsupported
    }
    // Obtain OAuth2 token from identity service using installation credentials
    // POST to ${push_relay_uri}/push/register with device metadata
}

This function validates the device through device.is_push_device() (defined in src/db/models/device.rs) before exchanging tokens with the relay.

Sending Push Notifications

Internal handlers invoke send_to_push_relay() to dispatch messages:

// src/api/push.rs
async fn send_to_push_relay(notification_data: Value) {
    if !CONFIG.push_enabled() {
        return;
    }
    // POST to ${push_relay_uri}/push/send with JSON payload
}

Higher-level functions like push_cipher_update() prepare event-specific data. For example, when updating a password entry:

// src/api/notifications.rs invokes:
use crate::api::push::push_cipher_update;
use crate::api::core::ciphers::UpdateType;

// Dispatch notification for cipher modification
push_cipher_update(UpdateType::Update, &cipher, &acting_device, &conn).await;

This generates a JSON payload structured as:

{
  "type": "cipherUpdate",
  "deviceId": "c0f7e6b2-...",
  "pushToken": "fcm_token_from_mobile",
  "installationId": "12345678-90ab-...",
  "objectId": "c0f7e6b2-...",
  "object": { /* encrypted cipher data */ }
}

Summary

• Vaultwarden implements mobile push notifications by integrating with the official Bitwarden push relay service, using credentials from the Bitwarden host portal.
• Enable the feature by setting PUSH_ENABLED=true and providing valid PUSH_INSTALLATION_ID and PUSH_INSTALLATION_KEY values in your environment configuration.
• The subsystem handles events including cipher changes, folder updates, authentication requests, and session terminations, defined primarily in src/api/push.rs and dispatched from src/api/notifications.rs.
• Mobile devices register FCM/APNs tokens via the /identity/register endpoint, stored alongside push_uuid values in the device model (src/db/models/device.rs).
• If push notifications are unavailable, the server gracefully degrades to WebSocket-based real-time updates when configured.

Frequently Asked Questions

What happens if I enable push notifications but provide invalid installation credentials?

Vaultwarden validates the presence of both PUSH_INSTALLATION_ID and PUSH_INSTALLATION_KEY during startup in src/config.rs. If either value is missing or empty while PUSH_ENABLED=true, the server logs an error message and disables push operations, effectively falling back to WebSocket notifications if available, or operating without real-time mobile updates.

Can I use Vaultwarden push notifications with custom FCM or APNs keys?

No. Vaultwarden relies on the official Bitwarden push relay infrastructure rather than direct FCM/APNs integration. You must use the standard PUSH_RELAY_URI and PUSH_IDENTITY_URI endpoints (or their custom equivalents if running a private Bitwarden-compatible relay), and authenticate using the Installation ID/Key pair from the Bitwarden host portal. Direct Firebase or Apple developer configuration is not supported.

Do push notifications work for all Bitwarden mobile clients?

Push notifications function with the official Bitwarden iOS and Android applications when configured against a Vaultwarden instance. Third-party or forked mobile clients may not implement the required /identity/register endpoint consumption or the specific payload parsing logic found in src/api/push.rs, which could prevent token registration or notification delivery.

How do I troubleshoot missing push notifications on mobile devices?

First, verify that PUSH_ENABLED is true and that your server logs show successful initialization of the push subsystem without credential errors. Check that the mobile device appears in your database with a valid push_token and push_uuid in the devices table. Ensure the mobile app has granted notification permissions at the OS level. If issues persist, inspect network connectivity between your Vaultwarden server and push.bitwarden.com, and review the send_to_push_relay() function logs for HTTP errors when posting to the relay endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}