Sessions and credentials
An ESPRMNeoUser holds three Cognito tokens, and the SDK exchanges them for the AWS credentials that MQTT and the signed REST APIs need. This page covers what a session holds, how it is extended, how the credential chain works, and how to end it.
You get a user from auth.login() or auth.getLoggedInUser(). See Authentication.
What a session holds
Three token properties, readable on the instance:
| Property | Used for |
|---|---|
accessToken | Authorising User API calls |
idToken | Credential exchange, MQTT client identity |
refreshToken | Extending the session |
The constructor persists all three through your storage adaptor, which is what makes getLoggedInUser() work on the next launch.
Extend a session
await ESPRMNeoUser.extendSession("<refresh-token>");
A static method returning Promise<void>. It refreshes the tokens and writes all three back to storage. Because it is static it updates storage, not the instance you are holding; re-read the session with getLoggedInUser() if you need an instance carrying the new tokens.
Use ESPRMNeoAuth.getRefreshedTokens() instead when you want the new tokens returned and nothing persisted.
The credential chain
Direct MQTT and the signed REST APIs run on AWS credentials, not Cognito tokens. Two calls produce them, in order:
connectMQTT() runs all three of those steps itself.
const temporary = await user.getTemporaryAWSCredentials();
const iot = await user.assumeRole(
temporary.accessKey,
temporary.secretKey,
temporary.sessionToken,
);
getTemporaryAWSCredentials() returns Promise<ESPAWSCredentials> — accessKey, secretKey, sessionToken and expiration. It authorises with the ID token and self-heals: if the token has expired locally, or the API answers 401 with an expired-token message, it refreshes the session and retries. It throws ESPTokenError when no ID or refresh token is stored.
assumeRole(accessKey, secretKey, sessionToken, options?) returns Promise<AWSCredentials>, note the snake_case shape, access_key, secret_key, session_token, expiration. This is not a refresh of the credentials you passed in: the backend uses them to assume an IAM role carrying IoT permissions and hands back a different set.
Pass options.include to widen the session policy beyond IoT:
const iot = await user.assumeRole(accessKey, secretKey, sessionToken, {
include: ["s3", "kvs"],
});
Omitting include grants IoT and MQTT permissions only.
user.connectMQTT() calls getTemporaryAWSCredentials() and then assumeRole() internally before connecting. Call the two directly only when you need the credentials for something else; signing your own requests, or an S3 or KVS client. There is no need to prime them before connecting.
Sign out
const ok = await user.logout();
logout() returns Promise<boolean>. It works through six steps, each of which is allowed to fail without aborting the rest: invalidate the server session, disconnect MQTT, reset the MQTT session state, clear the tokens, clear the stored AWS credentials, and clear the cached node configurations.
true means local cleanup finished. Because the steps are individually fault-tolerant, true does not promise the server-side sign-out succeeded; a device that was offline at sign-out still ends up locally clean. false means an unexpected error escaped the sequence, and the safest response is to treat the user as signed out anyway and re-check with getLoggedInUser().
Method summary
| Method | Returns |
|---|---|
extendSession(refreshToken) (static) | void |
getTemporaryAWSCredentials() | ESPAWSCredentials |
assumeRole(accessKey, secretKey, sessionToken, options?) | AWSCredentials |
logout() | boolean |
Related
- Authentication — where a session begins
- Live updates — what the IoT credentials are for
- Adaptors — the storage that persists a session
- Getting started with the API — the same chain at the REST level
- Errors —
ESPTokenErrorand friends