> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Introduction

## Article: Introduction

## Article Link: https://dev.wix.com/docs/sdk/core-modules/realtime/extensions/realtime-permissions-provider/introduction.md

## Article Content:

# About the Realtime Permissions Provider Service Plugin

As a realtime channel provider, you can integrate with Wix to control who can receive messages on your [Wix Realtime](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/introduction.md) channels. When a subscriber from another app attempts a [cross-app subscription](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/introduction.md#cross-app-subscriptions) to one of your channels, Wix calls your implementation to check whether that subscriber has permission to listen.

The integration is done via an app in the Wix App Market and by implementing the Realtime Permissions Provider [service plugin](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions.md). After the app is installed on a site, Wix calls your service whenever a subscriber from another app attempts to join one of your channels.

Implementing this service plugin lets you explicitly allow or deny access per channel for subscribers from other apps. Without a registered provider, Wix denies all cross-app subscription attempts by default.

## How this service plugin works

Wix calls your service plugin when a subscriber from another app attempts a [cross-app subscription](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/introduction.md#cross-app-subscriptions) to one of your app's [channels or resources](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/introduction.md#channels-and-channel-resources). The call is synchronous: Wix waits for your response before allowing or denying the subscription.

Wix uses the `read` value in your response to determine whether the subscriber can receive messages on the channel. Return `{ read: true }` to allow access, or `{ read: false }` to deny.

### Context provided with each call

Wix includes the following data with every Check Subscriber Permissions call. Use this data to apply your authorization logic.

| Input | Description |
| --- | --- |
| **Channel** | The [channel or resource](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/introduction.md#channels-and-channel-resources) the subscriber is joining, including the channel `name` and optional `resourceId`. |
| **Subscriber** | The [subscriber](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/subscriber/introduction.md) attempting the subscription, including their `type` (`ADMIN`, `MEMBER`, or `VISITOR`) and `id`. |
| **Requesting app ID** | The app ID of the app attempting the cross-app subscription. May be empty when the app context is unavailable. |

Wix also includes standard request context (site identifiers, identity, locale) with every service plugin call. Use this context to customize your implementation's behavior for different sites, identities, and scenarios.

## Requirements and constraints

Your service plugin implementation must meet the following requirements:

- Respond quickly. Slow handlers delay subscription checks. If your implementation doesn't respond in time, Wix denies the subscription with a 503 HTTP status code.
- Keep decisions consistent for the same channel, subscriber, and context so subscribers get consistent results.

### Error handling

Your service plugin must distinguish between policy denials and errors:

- Use `{ read: false }` for normal policy denials. Don't throw an error to deny access.
- Return `InvalidArgumentError` only when the request contains invalid or missing data that prevents your service from processing it.
- For any other failure (thrown error, timeout, or unreachable service), Wix denies the subscription with a 503 HTTP status code.

## Get started

Follow these steps to begin implementing your service plugin.

### Choose a framework

You can implement this service plugin with the following [frameworks](https://dev.wix.com/docs/build-apps/get-started/overview/wix-s-development-frameworks.md):

+ **Wix CLI:** Learn how to [implement a service plugin with the CLI and the SDK](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli.md).
+ **Self-hosted:** Learn how to [implement a self-hosted service plugin with the SDK and the Wix Dev Center](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md).

### Configure your service plugin

To configure and customize your plugin, provide the required information in the service plugin configuration file. You can [configure your plugin in your app's dashboard](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md#step-1--add-a-service-plugin-extension-to-your-app). For details, see [Realtime Permissions Provider Extension Configuration](https://dev.wix.com/docs/sdk/core-modules/realtime/extensions/realtime-permissions-provider/extension-config.md).

### Define handler functions

Use [`realtimePermissionsProvider.provideHandlers()`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md#step-4--define-handler-functions) to define the following handler functions that implement your custom authorization logic. Make sure you define all required functions.

| Method | Required |
| --- | --- |
| [`checkSubscriberPermissions()`](https://dev.wix.com/docs/sdk/core-modules/realtime/extensions/realtime-permissions-provider/check-subscriber-permissions.md) | Yes |

### Code examples

The following examples show the basic code structure for implementing the Realtime Permissions Provider service plugin.

#### Wix CLI

```js
import { realtimePermissionsProvider } from '@wix/realtime/service-plugins';

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

    // Allow members and admins, deny visitors.
    return { read: request.subscriber.type !== 'VISITOR' };
  },
});
```

#### Self-hosted

```js
import { createClient } from '@wix/sdk';
import { realtimePermissionsProvider } from '@wix/realtime/service-plugins';

const myWixClient = createClient({
  modules: { realtimePermissionsProvider },
  auth: {
    appId: '<YOUR_APP_ID>',
    publicKey: '<YOUR_PUBLIC_KEY>',
  },
});

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

    // Allow members and admins, deny visitors.
    return { read: request.subscriber.type !== 'VISITOR' };
  },
});

// Route service plugin traffic to the SDK client.
app.post('/plugins-and-webhooks/*', (req, res) => {
  myWixClient.process(req, res);
});
```

## Use cases

- [Check permissions for a cross-app subscription](https://dev.wix.com/docs/sdk/core-modules/realtime/extensions/realtime-permissions-provider/realtime-permissions-provider-service-plugin.md#check-permissions-for-a-cross-app-subscription)

## See also

+ [Realtime APIs](https://dev.wix.com/docs/sdk/core-modules/realtime/realtime/introduction.md)
+ [About Service Plugin Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions.md)
+ [Add Service Plugin Extensions with the Wix CLI](https://dev.wix.com/docs/wix-cli/guides/extensions/backend-extensions/service-plugins/add-service-plugin-extensions.md)
+ [Add a Self-hosted Service Plugin With the SDK](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md)

@sdk_package_setup