Azure Web PubSub service data plane REST API reference

As illustrated by the above workflow graph, and also detailed workflow described in internals, your app server can send messages to clients or to manage the connected clients using REST APIs exposed by Web PubSub service. This article describes the REST APIs in detail.

Important

Raw connection strings appear in this article for demonstration purposes only.

A connection string includes the authorization information your application needs to access Azure Web PubSub service. The access key in the connection string acts like a root password for your service. In production environments, always protect your access keys. Use Azure Key Vault to manage and rotate your keys securely and secure your connection with WebPubSubServiceClient.

Avoid distributing access keys to other users, hard-coding them, or saving them anywhere in plain text that is accessible to others. Rotate your keys if you believe they may have been compromised.

Using REST API

Group names and user IDs in request paths

REST operations that include a group name or user ID in the request path have a limitation with forward slashes (/) in these values. URL-encoding the slash as %2F might not resolve the limitation: the operation can fail to address the intended group or user. For example, a client connected with the user ID tenant/alice might not be found by a REST request whose path contains /users/tenant%2Falice.

This limitation applies to operations that use these path parameters, such as sending messages, checking whether a group or user exists, closing connections, and managing group membership. Server SDK methods that call these REST endpoints are subject to the same limitation. This is a REST request-path limitation, not a general prohibition on / in Web PubSub group names or user IDs.

To avoid the limitation, use group names and user IDs without / when your application needs these REST operations. If your application's identifiers contain /, map them to unique, slash-free identifiers and use the mapped values consistently in client access tokens, group membership, and REST calls. Changing only the value in the REST request doesn't change the user ID or group name associated with an existing connection.

Note

A 202 Accepted response from a send operation indicates that the request was accepted for processing. It doesn't confirm delivery to the intended user or group.

Authenticate via Azure Web PubSub Service AccessKey

In each HTTP request, an authorization header with a JSON Web Token (JWT) is required to authenticate with Azure Web PubSub Service.

Signing Algorithm and Signature

HS256, namely HMAC-SHA256, is used as the signing algorithm.

You should use the AccessKey in Azure Web PubSub Service instance's connection string to sign the generated JWT.

Claims

Below claims are required to be included in the JWT.

Claim Type	Is Required	Description
aud	true	Should be the SAME as your HTTP request url. For example, a broadcast request's audience looks like: https://example.webpubsub.azure.com/api/hubs/myhub/:send?api-version=2022-11-01.
exp	true	Epoch time when this token will be expired.

A pseudo code in JS:

Raw connection strings appear in this article for demonstration purposes only. In production environments, always protect your access keys. Use Azure Key Vault to manage and rotate your keys securely and secure your connection with WebPubSubServiceClient.

const bearerToken = jwt.sign({}, connectionString.accessKey, {
  audience: request.url,
  expiresIn: "1h",
  algorithm: "HS256",
});

Authenticate via Microsoft Entra token

Like using AccessKey, a JSON Web Token (JWT) is also required to authenticate the HTTP request.

The difference is, in this scenario, JWT is generated by Microsoft Entra ID.

Learn how to generate Microsoft Entra tokens

The credential scope used should be https://webpubsub.azure.com/.default.

You could also use Role Based Access Control (RBAC) to authorize the request from your server to Azure Web PubSub Service.

Learn how to add role assignments

APIs

Operation Group	Description
Service Status	Provides operations to check the service status
REST Operations	Provides operations to manage the connections and send messages to them.