How-to Guide: Common Tasks with TideCloak in Vanilla JS

Quick, copy-paste snippets for everyday tasks using @tidecloak/js.

---

Install

npm install @tidecloak/js

Ensure public/silent-check-sso.html exists (see tutorial) and place your adapter at ./tidecloak.json.

---

Initialize IAM

import { IAMService } from "@tidecloak/js";
import config from "./tidecloak.json";

await IAMService.initIAM(config);
// or override redirect:
await IAMService.initIAM({ ...config, redirectUri: "https://your.app/auth/callback" });

Default redirect: ${window.location.origin}/auth/redirect → ensure that path exists.

---

Login / Logout

IAMService.doLogin(); // redirect to SSO
IAMService.doLogout(); // clear and redirect

---

Tokens & Claims

const isLogged = IAMService.isLoggedIn(); // boolean
const token = await IAMService.getToken(); // access token (string)
const idToken = IAMService.getIDToken(); // ID token (string)

const exp = IAMService.getTokenExp(); // seconds since epoch
const username = IAMService.getName(); // preferred_username

const email = IAMService.getValueFromToken("email");
const sub = IAMService.getValueFromIDToken("sub");

---

Role Checks

IAMService.hasRealmRole("admin"); // boolean
IAMService.hasClientRole("editor"); // boolean (defaults to your app client)

---

Token Refresh

await IAMService.updateIAMToken(); // try to refresh if needed
await IAMService.forceUpdateToken(); // force refresh attempt

---

Events

const onReady = (auth) => console.log("Ready, logged in:", auth);
IAMService.on("ready", onReady);

// Later (SPA cleanup):
IAMService.off("ready", onReady);

Common events:

Event	When it fires
ready	Initial silent SSO finished (true/false)
authSuccess	Interactive login success
authError	Interactive login failed
authRefreshSuccess	Silent token refresh succeeded
authRefreshError	Silent token refresh failed
logout	User logged out
tokenExpired	Token expired before refresh

---

Encrypt / Decrypt (E2EE)

Requires roles per tag: _tide_<tag>.selfencrypt / _tide_<tag>.selfdecrypt

// Encrypt string values:
const [encDob] = await IAMService.doEncrypt([
  { data: "2005-03-04", tags: ["dob"] }
]);

// Decrypt back:
const [dob] = await IAMService.doDecrypt([
  { encrypted: encDob, tags: ["dob"] }
]);

// Multi-field example:
const encrypted = await IAMService.doEncrypt([
  { data: "10 Smith Street", tags: ["street"] },
  { data: "Southport", tags: ["suburb"] },
  { data: "20 James Street - Burleigh Heads", tags: ["street", "suburb"] }
]);

const decrypted = await IAMService.doDecrypt([
  { encrypted: encrypted[0], tags: ["street"] },
  { encrypted: encrypted[1], tags: ["suburb"] },
  { encrypted: encrypted[2], tags: ["street", "suburb"] }
]);

data must be string or Uint8Array. Output order matches input order.

---

Protecting Backend APIs

Send the access token as a bearer:

const token = await IAMService.getToken();
const res = await fetch("/api/secure", {
  headers: { Authorization: `Bearer ${token}` }
});

Verify the JWT in your backend (Node, Go, etc.) using your realm's JWKS.