# Vaultwarden Push Notification Support: Configuration and Implementation Guide

> Enable Vaultwarden push notifications for real-time sync. Learn to configure Bitwarden push relay service and set PUSH_ENABLED=true with this implementation guide.

- Repository: [Daniel García/vaultwarden](https://github.com/dani-garcia/vaultwarden)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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`](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/push.rs)** – Handles low-level device registration and relay communication
- **[`src/api/notifications.rs`](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/notifications.rs)** – Dispatches high-level events to the push subsystem
- **[`src/db/models/device.rs`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/push.rs) and invoked from [`src/api/notifications.rs`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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:

   ```dotenv
   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`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/push.rs) manages the initial handshake with the Bitwarden relay:

```rust
// 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`](https://github.com/dani-garcia/vaultwarden/blob/main/src/db/models/device.rs)) before exchanging tokens with the relay.

### Sending Push Notifications

Internal handlers invoke `send_to_push_relay()` to dispatch messages:

```rust
// 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:

```rust
// 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:

```json
{
  "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`](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/push.rs) and dispatched from [`src/api/notifications.rs`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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.