Multiplex

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.

Multiplex in cloud-to-cloud integration

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.

Recommendations

  • 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

  1. Use the multiplex endpoint: https://developer-api.nest.com/multiplex
  2. 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"

Request

Parameter name Type Required Description
LIST_OF_ACCESS_TOKENS



list



Required



• Comma-separated list of access_tokens
• Format: token1,token2,token3
• Recommended number of tokens: 10-20
• Maximum number of tokens per multiplex connection: 50

Response

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 LIST_OF_ACCESS_TOKENS:

  1. Close the connection
  2. Modify the LIST_OF_ACCESS_TOKENS
  3. Make the multiplex call again

Error response

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.

Best practices

To re-establish multiplex connections:

  1. Make the multiplex call for your first connection
  2. Wait at least 10 seconds
  3. 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 cancel and auth_revoked messages in the stream, and handle any tokens that are canceled/revoked.

New permissions event

Client update
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 connection, your product receives an auth_revoked event and stops receiving data for that token.

After an 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 token/user.