Azure SignalR service data plane REST API reference

Note

Azure SignalR Service only supports using REST API to manage clients connected using ASP.NET Core SignalR. Clients connected using ASP.NET SignalR use a different data protocol that is not currently supported.

On top of the classical client-server pattern, Azure SignalR Service provides a set of REST APIs so that you can easily integrate real-time functionality into your server-less architecture.

Typical Server-less Architecture with Azure Functions

The following diagram shows a typical server-less architecture using Azure SignalR Service with Azure Functions.

• negotiate function returns a negotiation response and redirects all clients to SignalR Service.
• broadcast function calls SignalR Service's REST API. Then SignalR Service will broadcast the message to all connected clients.

In a server-less architecture, clients still have persistent connections to the SignalR Service. Since there's no application server to handle traffic, clients are in LISTEN mode, which means they can only receive messages but can't send messages. SignalR Service will disconnect any client that sends messages because it's an invalid operation.

You can find a complete sample of using SignalR Service with Azure Functions at here.

API

The following table shows all versions of REST API we have for now. You can also find the swagger file for each version of REST API.

API Version	Status	Port	Doc	Spec
1.0	Latest	Standard	Doc	swagger
1.0-preview	Obsolete	Standard	Doc	swagger

The latest available APIs are listed as following.

API	Path
Broadcast a message to all clients connected to target hub.	POST /api/v1/hubs/{hub}
Broadcast a message to all clients belong to the target user.	POST /api/v1/hubs/{hub}/users/{id}
Send message to the specific connection.	POST /api/v1/hubs/{hub}/connections/{connectionId}
Check if the connection with the given connectionId exists	GET /api/v1/hubs/{hub}/connections/{connectionId}
Close the client connection	DELETE /api/v1/hubs/{hub}/connections/{connectionId}
Broadcast a message to all clients within the target group.	POST /api/v1/hubs/{hub}/groups/{group}
Check if there are any client connections inside the given group	GET /api/v1/hubs/{hub}/groups/{group}
Check if there are any client connections connected for the given user	GET /api/v1/hubs/{hub}/users/{user}
Add a connection to the target group.	PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Remove a connection from the target group.	DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Check whether a user exists in the target group.	GET /api/v1/hubs/{hub}/groups/{group}/users/{user}
Add a user to the target group.	PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}
Remove a user from the target group.	DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}
Remove a user from all groups.	DELETE /api/v1/hubs/{hub}/users/{user}/groups

Using REST API

Authenticate via Azure SignalR Service AccessKey

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

Signing Algorithm and Signature

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

Use the AccessKey in Azure SignalR Service instance's connection string to sign the generated JWT token.

Claims

The following claims are required to be included in the JWT token.

Claim Type	Is Required	Description
aud	true	Needs to be the same as your HTTP request url, trailing slash and query parameters not included. For example, a broadcast request's audience should look like: https://example.service.signalr.net/api/v1/hubs/myhub.
exp	true	Epoch time when this token expires.

Authenticate via Azure Active Directory Token (Azure AD Token)

Similar to authenticating using AccessKey, when authenticating using Azure AD Token, a JSON Web Token (JWT) is also required to authenticate the HTTP request.

The difference is, in this scenario the JWT Token is generated by Azure Active Directory.

Learn how to generate Azure AD Tokens

You could also use Role Based Access Control (RBAC) to authorize the request from your client/server to SignalR Service.

Learn how to configure Role-based access control roles for your resource

Implement Negotiate Endpoint

As shown in the architecture section, you should implement a negotiate function that returns a redirect negotiation response so that client can connect to the service. A typical negotiation response looks as follows:

{
    "url":"https://<service_name>.service.signalr.net/client/?hub=<hub_name>",
    "accessToken":"<a typical JWT token>"
}

The accessToken is generated using the same algorithm described in authentication section. The only difference is the aud claim should be same as url.

You should host your negotiate API in https://<hub_url>/negotiate so you can still use SignalR client to connect to the hub url.

Read more about redirecting client to Azure SignalR Service at here.

User-related REST API

In order to call user-related REST API, each of your clients should identify itself to SignalR Service. Otherwise SignalR Service can't find target connections from a given user ID.

Client identification can be achieved by including a nameid claim in each client's JWT token when they're connecting to SignalR Service. Then SignalR Service will use the value of nameid claim as the user ID of each client connection.

Sample

You can find a complete console app to demonstrate how to manually build a REST API HTTP request in SignalR Service here.

You can also use Microsoft.Azure.SignalR.Management to publish messages to SignalR Service using the similar interfaces of IHubContext. Samples can be found here. For more information, see How to use Management SDK.

Limitation

Currently, we have the following limitation for REST API requests:

• Header size is a maximum of 16 KB.
• Body size is a maximum of 1 MB.

If you want to send message larger than 1 MB, use the Management SDK with persistent mode.