SDK Reference

Every export, grouped, and what the API does not have.

Every export, grouped by what it is for. Types are omitted except where the type is the point.

Everything here is importable from @guacamole_hbai/auth. The receiver also lives at @guacamole_hbai/auth/caep, which needs no API key — use that import in a web tier that verifies events but provisions nobody.

The client¶

new Guacamole({ apiKey, tenant, baseUrl, clientId?, timeoutMs?, retry?, transport?, userAgent? })


`gid.subjects`	`create` · `get` · `getBySub` · `list` · `iterate` · `suspend` · `deactivate` · `erase`
`gid.enrollments`	`invite` · `status`
`gid.credentials`	`list` · `revoke`
`gid.identifications`	`start` · `get`
`gid.audit`	`authentications`
`gid.streams`	`ensure` · `get` · `verify`
`gid.receiver(options)`	a `Receiver` with the issuer already right
`gid.tokens`	a `Tokens` with the issuer and client id already right

See Managing people.

Claims and `acr`¶


`verifyClaims(claims, options)`	the `acr` and freshness check; returns `VerifiedClaims`
`assertVerified(claims)`	the boundary tripwire — throws on an unbranded set
`AcrNotSatisfied`	a step-up, not a bad token
`VerifiedClaims`	branded, frozen; type your session code to take it
`Tokens` / `IdTokenInvalid`	the whole ID-token check, where no OIDC library runs

The acr values:


`ACR_FACE`	`urn:guacamole:acr:face`
`ACR_FACE_PASSKEY`	`urn:guacamole:acr:face-passkey`
`ACR_FACE_ONLY_UNVERIFIED`	`urn:guacamole:acr:face-only-UNVERIFIED`
`ACR_PASSIVE_PRESENCE`	`urn:guacamole:acr:passive-presence`
`ACR_POSSESSION_ONLY`	`urn:guacamole:acr:possession-only-UNVERIFIED`

The two with UNVERIFIED in the string are named that way so they cannot be skimmed past in a log. See Verifying tokens.

Receiving events¶


`Receiver`	`on` · `receive` · `handler` · `nodeHandler`
`webHandler` / `nodeHandler`	the same handlers, standalone
`InMemoryReplayStore` · `RedisReplayStore`	`"memory"` is shorthand for the first
`JwksCache` · `KeyUnavailable`	key fetching, if you need it directly
`InvalidSecurityEvent`	a token that did not verify
`SECEVENT_CONTENT_TYPE` · `SECEVENT_TYP`	`application/secevent+jwt`
`DEFAULT_LEEWAY_SECONDS` · `DEFAULT_MAX_AGE_SECONDS` · `DEFAULT_TTL_SECONDS` · `MINIMUM_TTL_SECONDS`	the defaults, as values

Event types:


`SESSION_REVOKED`	stop trusting this session
`ASSURANCE_LEVEL_CHANGE`	presence changed during a watch
`CREDENTIAL_CHANGE`	a template or passkey was created, updated, revoked or deleted
`VERIFICATION`	a test of the channel; names nobody
`SUBSCRIBABLE_EVENT_TYPES`	the ones a stream may ask for

Readers — all of them tolerate a malformed event rather than throwing inside your handler:


`subjectOf`	the `sub`, or `null`
`sessionIdOf`	which watch — one person can have two at once
`isPresenceLost`	an explicit `current_level: null`, not an absent key
`currentLevelOf` · `previousLevelOf`	the assurance levels
`reasonCodeOf`	machine-readable; never match on the prose
`reasonForUser` · `reasonForAdmin`	the prose, for showing a person
`gapToleranceOf`	the provider's own deadline, as a number
`credentialTypeOf` · `changeTypeOf`	for `credential-change`
`canReauthenticate`	whether signing in again could recover the watch

Watch reason codes — REASON_PRESENT, REASON_ABSENT, REASON_MISMATCH, REASON_GAP_EXCEEDED, REASON_UNREADABLE, REASON_WATCH_ENDED, REASON_ADMINISTRATIVE, and WATCH_REASON_CODES for the set.

Credential change types — CHANGE_TYPE_CREATE, CHANGE_TYPE_UPDATE, CHANGE_TYPE_REVOKE, CHANGE_TYPE_DELETE, and CREDENTIAL_TYPE_FACE_TEMPLATE.

See Receiving events.

Enrolment outcomes¶

ENROLLMENT_STATUSES and ENROLLMENT_FAILURES are the sets; ENROLLMENT_COMPLETED, ENROLLMENT_IN_PROGRESS, ENROLLMENT_DECLINED, ENROLLMENT_EXPIRED and ENROLLMENT_FAILED are the statuses.

The eight failures: SPOOF_DETECTED, DUPLICATE_ENROLLMENT, LIVENESS_NOT_EVALUATED, LIVENESS_UNAVAILABLE, NO_USABLE_FACE, CAMERA_UNAVAILABLE, INTERRUPTED, PASSKEY_FAILED. CLIENT_REPORTED_FAILURES names the five the page reported rather than the server.


`canRetry(code)`	whether a fresh invitation can possibly help
`describeEnrollmentFailure(code)`	a sentence for an operator

canRetry is false for three of the eight — check it before offering "try again", or you send somebody back to the camera for a ceremony that will reach the same verdict. An unknown code returns true, so a reason added later does not dead-end anybody.

Errors¶

GuacamoleError is the base. AuthenticationError, ScopeError, NotFoundError, ConflictError, ValidationError, RateLimitError, ServerError, TransportError, ConfigurationError, NotImplementedByServer.

Retries: DEFAULT_RETRY, NO_RETRY, and RetryPolicy to write your own.

Transport¶

FetchTransport is the default. Transport is the interface, for tests or a proxy — GuacamoleRequest and GuacamoleResponse are its shapes.

Probes¶

probeFromPayload, ProbeInvalid, EMBEDDING_DIMENSIONS, ARCFACE_DIMENSIONS. For deployments that submit a probe computed elsewhere.

Not in the API¶

If you are looking for one of these, it does not exist and will not be added: an accessor for a template, an embedding or an image; a similarity score, threshold or confidence; a candidate list or count; a distinction between "nobody matched" and "nobody is enrolled"; a test mode or bypass flag.