Authenticate and tokens — Cliodot Documentation

Prefer provider() for internal Cliodot Identity Apps and extProvider() for External Application Profiles. Low-level authenticate({ target_app_id }) remains available.

Internal Identity Apps — `provider()`#

const hrms = identity.provider("identity_hrms");
const tokens = await hrms.authenticate();
await hrms.verify(tokens.access_token);
await hrms.refresh(tokens.refresh_token!);

provider() never resolves External Profiles (ext: / ext_).

External Application Profiles — `extProvider()`#

const hrms = identity.extProvider("hrms");
const tokens = await hrms.authenticate();
await hrms.verify(tokens.access_token);
await hrms.refresh(tokens.refresh_token!);

Maps to target_app_id: "ext:hrms". extProvider() never resolves Identity Apps.

Low-level authenticate#

Caller app authenticates to a trusted target. The target must allowlist the caller in the portal (same-tenant direct trust, or cross-tenant trust invite accepted by the caller tenant).

const tokens = await identity.authenticate({
  target_app_id: "identity_hrms",
});

console.log(tokens.access_token);
console.log(tokens.refresh_token);
console.log(tokens.expires_in);

When the target has scopes enabled:

const tokens = await identity.authenticate({
  target_app_id: "identity_hrms",
  scopes: ["employees.read"],
});

Issuance (when scopes are enabled on the target):

Omit scopes → receive the full trust grant (empty grant = entire catalog)
Pass scopes → receive only that subset (must be within the grant)

Access JWTs include a scope claim as a string array when non-empty.

Maps to POST /identity/v1/authenticate → access JWT (+ optional refresh).

Verify (online)#

Cliodot re-checks signature, expiry, revocation, and trust:

const verified = await identity.verify({
  access_token: tokens.access_token,
});

const bound = await identity.verify({
  access_token: tokens.access_token,
  target_app_id: "identity_hrms",
});

const scoped = await identity.verify({
  access_token: tokens.access_token,
  required_scopes: ["employees.read"],
});

required_scopes requires the scopes license; missing scopes → IDENTITY_SCOPE_INSUFFICIENT. Maps to POST /identity/v1/verify or POST /identity/v1/apps/:appId/verify.

Refresh / revoke#

const rotated = await identity.refresh({
  refresh_token: tokens.refresh_token!,
});

await identity.revoke({
  refresh_token: tokens.refresh_token,
});

Maps to POST /identity/v1/token/refresh and POST /identity/v1/token/revoke.

JWKS#

Unauthenticated public keys for RS256 targets (requires RS256 license on the platform):

const jwks = await identity.getJwks("identity_hrms");

Maps to GET /identity/v1/apps/:appId/jwks.json.

import { createIdentityTokenCache } from "cliodot";

const cache = createIdentityTokenCache({ client: identity });
const accessToken = await cache.getAccessToken("identity_hrms");

Authenticates on miss; refreshes when a refresh token is available; clears near expiry with a skew window.

Internal Identity Apps — provider()#