Sign in

Refresh the Session

This guide shows how to restore a MonoCloud session silently on app start and refresh the tokens stored on the session without an interactive sign-in.

What you'll cover

  • Restore the session silently via a hidden iframe with signInSilent()
  • Renew the tokens on the current session with refreshSession()
  • Refresh the user profile with refetchUserInfo()

Before you begin

This guide assumes you've completed the JavaScript quickstart or the installation guide.

You should already have:

  • A Single Page App configured in MonoCloud
  • The @monocloud/auth-web-js SDK installed
  • A MonoCloudWebJSClient initialized
refreshSession() requires a refresh token. Enable Refresh Tokens on the application to use the offline_access scope.

When to use which method

The SDK exposes two ways to keep a user signed in without an interactive sign-in:

MethodWhat it does
signInSilent()Opens a hidden iframe with prompt=none to restore the session from the authorization server
refreshSession()Uses the stored refresh token to renew the tokens on the current session

Restore the session on app load

Call signInSilent() and catch MonoCloudOPError for the case where the user is not signed in at the authorization server.

src/main.ts
import { MonoCloudOPError } from "@monocloud/auth-web-js";

try {
  await client.signInSilent();
} catch (error) {
  if (error instanceof MonoCloudOPError) {
    // user is not signed in
  } else {
    throw error;
  }
}

How it works:

  • signInSilent() opens a hidden iframe that hits the authorize endpoint with prompt=none
  • If the user has an active session with the authorization server, the iframe completes the code flow and a new session is persisted
  • If the user is not signed in (or consent is required), signInSilent() throws MonoCloudOPError

Refresh the session

Call refreshSession() to run the refresh token grant and update the stored session with new tokens.

src/auth.ts
await client.refreshSession();
const session = await client.getSession();

How it works:

  • The SDK calls the token endpoint using the stored refresh token
  • New access tokens and ID token are persisted on the session
  • The refresh token itself may rotate, depending on your application configuration

refreshSession() does not return tokens — read them from getSession() afterwards.

Override scopes and resources on a refresh

Pass refreshGrantOptions to scope the refresh to specific scopes or resources without changing the client-level configuration.

src/auth.ts
await client.refreshSession({
  refreshGrantOptions: {
    scopes: "openid profile email offline_access",
    resource: "https://api.example.com",
  },
});

The requested scopes and resources must already be allowed for the client. If they aren't, the authorization server rejects the request.

Handle a failed refresh

refreshSession() throws MonoCloudOPError when the refresh token has been revoked or has expired. Catch it and prompt the user to sign in again.

src/auth.ts
import { MonoCloudOPError } from "@monocloud/auth-web-js";

try {
  await client.refreshSession();
} catch (error) {
  if (error instanceof MonoCloudOPError) {
    // refresh token is no longer valid
  } else {
    throw error;
  }
}

Refresh user profile data

Call refetchUserInfo() to fetch the updated profile from the UserInfo endpoint and update session.user in place.

src/main.ts
await client.refetchUserInfo();
const session = await client.getSession();

Next steps

© 2024 MonoCloud. All rights reserved.