Multiplex enables you to have multiple users per open socket. This means you can use the Nest API to access Nest device data for a list of tokens and paths. A list of tokens/users represents people who have authorized you to access Nest device data.
On top of the REST stream, you can send a collection of tokens, and associated end user IDs or structure IDs. You can then observe each server-sent event notifying you that a state change has occurred from a particular structure.
Complications of using multiplex
Before you put multiplex into production, be aware of its limitations and complexities.
Multiplex increases complexity when dealing with revoked tokens and connection loss from a subset of tokens/users.
A single collection of tokens might not be sufficient to pass all events for all end users. A collection can vary in size from 1 to 50 users. If you have over 50 users, a single collection is not adequate.
It is not possible to add, at runtime, a single token to an existing collection of tokens.
What this means in practice is that you must start multiple individual REST streaming connections, one for each token until you accumulate enough tokens (say 50). Then create a multiplex connection with the collection of 50 tokens and disconnect the individual REST streaming connections.
Do not group smaller multiplex connections together into larger multiplex connections.
When you make a call to the multiplex endpoint, the response includes all data for each access token, including all structures and all devices.
We return an obfuscated user ID. We no longer recommend that clients depend on
access_token-to-user mappings because access tokens can be short-lived and refreshed.
It is not possible to limit the call to request specific data values. All data values (for all structures and all devices) are returned for each access token in the request.
When you create a new Works with Nest client, begin with REST Streaming.
If you get to the point where you have ~5000 connections, consider using multiplex.
If you decide to investigate multiplex, we recommend that you contact us first by working with your Partner Manager or by sending feedback.
How to make a multiplex call
- Use the multiplex endpoint:
- Make a REST Streaming call and include a list of (comma-separated) access tokens. We recommend you comply with this OAuth standard, which offers increased security by using the "Bearer" authentication scheme to transmit the access token. Calls with client credentials in the URL do work, but are not recommended.
curl -v --location-trusted -H "Accept:text/event-stream" \ -H "Authorization: Bearer LIST_OF_ACCESS_TOKENS" \ -X GET "https://developer-api.nest.com/multiplex"
||• Comma-separated list of
• Recommended number of tokens: 10-20
• Maximum number of tokens per multiplex connection: 50
The multiplex response includes all data values in all objects, as well as metadata. Your product must map access tokens to the corresponding users, and filter the data values for the information your product needs.
For more info, see the REST Streaming Guide.
How to change the list of access tokens
When you want to add or remove an access token, we recommend that you close the connection before modifying the list.
To change the
- Close the connection
- Modify the
- Make the multiplex call again
Typically, errors occur when:
- An access token in the list is invalid or missing
- You make too many calls too quickly, and get a rate limit error message (429 Too Many Requests)
Here are the most common HTTP status codes you might see:
|HTTP status code||Description/Troubleshooting|
|200 OK||Successful call|
|401 Unauthorized||Invalid/missing/malformed access token, or the list is incorrect or not formatted properly|
|404 Not Found||The Accept header is the wrong type, or is missing|
|500 Internal Server Error||The Nest service may be down—check Nest system status for more information|
Re-establish the connection
You'll need to re-establish multiplex connection if you introduce a new product with new, updated, or different permissions.
To re-establish multiplex connections:
- Make the multiplex call for your first connection
- Wait at least 10 seconds
- Make the next call
If the reconnect fails, you should try to reestablish the connections with a
10-20 second delay between attempts. Watch for
messages in the stream, and handle any tokens that are canceled/revoked.
New permissions event
When you update permissions, your users receive a message that permissions have changed. Users must accept the permission update before they can use the features associated with those new permissions. For more info, see Manage Client Version.
When you use REST Streaming with the multiplex endpoint and a user agrees to the permissions change, the Nest service:
- Keeps the multiplex connection open (so other user sessions aren't affected)
- Closes/ends the session associated with that user's access token (which prevents your product from receiving any further data for that access token)
You'll receive a cancel event that includes the user's access token:
event: cancel data: c.rCBqzTINcakt...
You should then reestablish the connection using this access token in your next new multiplex connection.
Works with Nest connection closed
If a user removes a Works with Nest
your product receives an
auth_revoked event and stops receiving data for
auth_revoked event, the multiplex connection stays up.
However, the revoked token is now invalid. You can adjust
subsequent multiplex calls to handle the loss of that