Skip to content
← Open Cap Table Protocol Canton Node SDK

Reference

AuthenticationManager

OAuth2 and alternative bearer flows for Canton HTTP clients — token cache, refresh window, bearerToken, tokenGenerator, and clearToken.

AuthenticationManager wraps @hardlydifficult/rest-client’s authentication delegate. Each manager instance corresponds to one (authUrl, AuthConfig) pair; CantonRuntime caches managers by a normalized key so ledger and validator clients sharing the same credentials reuse one token cache.

You rarely construct it directly — obtain it via canton.runtime.getAuthenticationManager(authUrl, authConfig) or implicitly through BaseClient.authenticate().

import type { AuthenticationManager } from '@fairmint/canton-node-sdk';

For concrete construction, the package re-exports the class from core/auth.

Example — force refresh after WebSocket close

import { Canton } from '@fairmint/canton-node-sdk';

const canton = new Canton({
  network: 'devnet',
  provider: '5n',
  partyId: 'OWN_PARTY_ID',
});

const token = await canton.ledger.authenticate();
console.log('Bearer prefix', token.slice(0, 12));

// Later: participant closed connection with auth expiry
canton.ledger.clearToken();
await canton.ledger.authenticate();

Supported auth shapes (AuthConfig)

The discriminated union on grantType plus optional overrides:

  • client_credentials — clientId, optional clientSecret, optional audience, scope. Uses authUrl as OAuth2 token endpoint (trailing slash normalized internally).
  • password — username, password, clientId, optional audience, scope.
  • Static bearer — bearerToken set: no OAuth round-trip; token sent as-is.
  • tokenGenerator — Async () => Promise<string> for dynamic bearer material (shared-secret JWTs, external issuers).
  • Empty clientId — Converts to rest-client none auth; warns if authUrl is set but client id empty — requests may run without Authorization header.

Priority when converting to rest-client config: bearerToken first, then tokenGenerator, then empty client id branch, then OAuth2 by grant type.

Methods

  • authenticate(): Promise<string> — Returns a usable bearer token. Uses cached token when inside validity window; otherwise refreshes. Concurrent callers share one in-flight promise (pendingAuthentication).
  • getBearerToken() — Alias for authenticate().
  • clearToken() — Bumps an internal generation counter, clears delegate cache, drops pending auth. Next authenticate() performs a fresh exchange or generator call.
  • getTokenExpiryTime() / getTokenIssuedAt() / getTokenLifetimeMs() — Delegate pass-throughs for scheduling proactive refresh (WebSockets, long polls).

Validity uses a sliding buffer before expiry (five minutes or half lifetime, whichever is smaller).

Errors and pitfalls

  • OAuth failures: Network or IdP errors surface from the delegate (often wrapped as AuthenticationError upstream via HTTP layer depending on call site).
  • FAIRMINT_AUTH_DEBUG: Set to 1/true/yes/on and oauth2-type configs to log structured cache-state lines to stdout ([FAIRMINT_AUTH_DEBUG]).
  • Generator identity: CantonRuntime keys cached managers using a synthetic id per tokenGenerator function reference — distinct closures create distinct caches even if behavior is identical.

See also

  • BaseClient — authenticate, clearToken, expiry helpers per API client.
  • CantonRuntime — registry of AuthenticationManager instances.
  • EnvLoader — where client_credentials / password env vars become AuthConfig.

Source

src/core/auth/AuthenticationManager.ts on GitHub.