/wix-app

Realtime Permissions Provider Service Plugin Reference

Overview

The Realtime Permissions Provider SPI controls who can receive messages on your app's Wix Realtime channels. When a subscriber from another app attempts a cross-app subscription to one of your channels, Wix calls your checkSubscriberPermissions handler and waits synchronously for the answer. Without a registered provider, Wix denies all cross-app subscription attempts by default.

This is the only SPI outside eCommerce and Bookings — it belongs to the Realtime module.

Request and Response Schema

Before implementing, call ReadFullDocsMethodSchema on the docs URL to get the full request/response types.

The request gives you the channel (name + optional resourceId), the subscriber (type: ADMIN / MEMBER / VISITOR, and _id), and requestingAppId (the app attempting the subscription, may be empty). Return { read: true } to allow, { read: false } to deny.

Example: Allow Members and Admins, Deny Visitors

import { realtimePermissionsProvider } from "@wix/realtime/service-plugins";

realtimePermissionsProvider.provideHandlers({
  checkSubscriberPermissions: async (payload) => {
    const { request } = payload;
    const { subscriber, channel } = request;

    if (channel?.name === "public-updates") {
      return { read: true };
    }

    return { read: subscriber?.type !== "VISITOR" };
  },
});

Key Implementation Notes

1. The generated stub may include a write field — remove it. wix generate for this pluginType has been observed scaffolding a response of { read: true, write: false }, but CheckSubscriberPermissionsResponse only has read?: boolean. Confirm against the installed @wix/auto_sdk_duplexer_realtime-permissions-provider types if tsc doesn't catch it for you.
2. channel and subscriber are both optional on the request — channel?: Channel, subscriber?: Subscriber. Accessing .name/.type without the ?. above fails tsc with "possibly undefined."
3. Deny with data, not errors — return { read: false } for normal policy denials. Only throw InvalidArgumentError when the request itself is invalid or missing data; any other thrown error, timeout, or unreachable service makes Wix deny the subscription with a 503.
4. Respond quickly — the call is synchronous and blocks the subscription attempt; a slow handler delays it, and a non-responsive one causes a 503 denial.
5. Be consistent — the same channel, subscriber, and context should always yield the same decision.
6. No provider means no cross-app access — until you implement this SPI, all cross-app subscription attempts to your channels are denied by default.