Skip to main content

Assume Role

Obtain temporary AWS credentials for MQTT or video streaming.

note

userInstance — ESPRMUser from User sign in.

What This Module Does ?​

assumeRole returns short-lived accessKey, secretKey, and sessionToken for RainMaker-backed services—typically MQTT for live device data or video stream for camera WebRTC (Kinesis Video Streams).

Use when your client connects directly to AWS MQTT/KVS—not for ordinary REST calls through the SDK.

Expected outcome: Credentials scoped to the requested role and optional group or node IDs.

Common Workflows​

MQTT credentials​

import { ESPUserRole } from "@espressif/rainmaker-base-sdk";

const credentials = await userInstance.assumeRole({
  userRole: ESPUserRole.MQTT,
  groupIds: ["group_id_1"],
});

Video stream credentials​

const credentials = await userInstance.assumeRole({
  userRole: ESPUserRole.VIDEOSTREAM,
  nodeIds: ["camera_node_id"],
});

Use the response with your AWS/KVS or WebRTC client. Resolve IDs via Get Groups and Node Management.

Error Handling​

try {
  await userInstance.assumeRole({ userRole: ESPUserRole.VIDEOSTREAM, nodeIds: [] });
} catch (error) {
  console.error("Assume role failed:", error);
}

videostream requires at least one nodeId. Do not pass both groupIds and nodeIds in one request.

Advanced Concepts​

Roles​

RoleValuePurpose
MQTTmqttDefault; MQTT for groups or nodes
Video streamvideostreamCamera streaming; requires nodeIds

Omit userRole to default to mqtt.

Validation​

  • Max 5 groupIds and 5 nodeIds
  • Not both groupIds and nodeIds in the same call
  • videostream must include at least one nodeId
  • For mqtt with empty IDs, credentials may cover all groups the user can access
warning

Treat credentials as secrets. Do not log them. Refresh before expiry per your AWS client.

Best Practices​

  1. Request minimal scope—pass specific groupIds or nodeIds when possible
  2. Do not persist credentials longer than the session needs
  3. Use Sessions for user auth tokens; assumeRole is separate from login

On this page