Node client reference

This page lists the configuration options and exports of @sidub-inc/licensing-client, which works in plain Node and in React.

LicensingClient config

Field	Required or optional	Meaning
licenseServiceUri	Required	The licensing API URL to call.
encodedCredential	Required, unless using the manual parts below	The encoded credential (SIDUB_LIC_...) that authenticates the client. It is decoded into seatId, serviceKeyId, serviceKeyPublicMember and runtimeToken.
runtimeToken	Required if not using encodedCredential	The seat-scoped runtime token. Opaque — never decode, parse or display it. Normally arrives inside encodedCredential rather than being set directly.
seatId	Required if not using encodedCredential	The seat ID component of the manual credential.
serviceKeyId	Required if not using encodedCredential	The service key ID component of the manual credential.
serviceKeyPublicMember	Required if not using encodedCredential	The service key public member component of the manual credential.
consumptionServiceUri	Optional	The consumption API URL to call.
timeout	Optional	The request timeout for calls to the licensing service.
validateSignatures	Optional	Whether to validate response signatures.
cacheEnabled	Optional	Whether to cache authorization results.
cacheMaxSize	Optional	The maximum size of the authorization cache.
cacheFreshTtlMs	Optional	How long, in milliseconds, a cached authorization is served before the client revalidates it against the licensing service. Default 24 hours (also the cap); an authorization with no expiry defaults to 1 hour. Revocation latency is min(cacheFreshTtlMs, remaining seat window) — tighten it for faster revocation pickup at the cost of more calls; 0 revalidates on every read.
staleGraceMs	Optional	How long, in milliseconds, an expired cached authorization may still be served (flagged stale) when the licensing service is transiently unreachable. Default 24 hours, capped at 7 days; 0 disables stale-serve. The Node analogue of .NET’s AuthorizationStaleGraceMinutes.
contextProvider	Optional	A custom context provider for multi-tenant credential resolution: an object whose resolveContext() returns the credential parts for the current caller, in place of the fixed credential above.
billableResourceId	Optional	The billable resource ID to report consumption against.

Exports

Export	Kind	Meaning
LicensingClient	Client	The client class, configured as shown above.
LicensingProvider	React	Context provider that makes a LicensingClient available to a React tree.
useLicensingContext	React hook	Reads the licensing context provided by LicensingProvider.
ServiceAccessAssertion	Assertion	Asserts that the license has access to the service.
FeatureExistsAssertion	Assertion	Asserts that a given feature exists on the license.
RateLimitAssertion	Assertion	Asserts that a rate-limited feature has not exceeded its limit.
QuotaAssertion	Assertion	Asserts that an allowance still has uses left in the current billing period.
CompositeAssertion	Assertion	Combines multiple assertions into one.
NotAssertion	Assertion	Inverts another assertion.
LicensingError	Error	The base error the client throws.
LicensingConfigurationException	Error	Thrown when the client configuration is invalid or incomplete.
CryptoError	Error	Thrown when signature verification fails.
RateLimitError	Error	Thrown when a rate-limited operation exceeds its limit.
encodeCredential, decodeCredential, tryDecodeCredential	Helper	Convert between the credential parts and the encoded SIDUB_LIC_... string.
hasValidCryptoConfig	Helper	Reports whether a decoded credential carries both serviceKeyId and serviceKeyPublicMember — the pair signature verification needs.
LicensingCredential	Type	The decoded credential: seatId, serviceKeyId, serviceKeyPublicMember and runtimeToken, all required. License codes are version 2 only; decodeCredential refuses a version 1 payload (which named the seat licenseId) rather than reinterpreting it.
licensingContextFromEncodedString, licensingContextToEncodedString	Helper	Convert a licensing context to and from its encoded form.
RateLimitFeatureState	Type	The state carried through rate-limited operations.

Credential posture

A credential carries one authority: the runtime token for the seat it names. The client calls {licenseServiceUri}/runtime and {consumptionServiceUri}/runtime, and presents the token as Authorization: Bearer. The /runtime suffix is derived by the client, so the configured URIs are the plain addresses. No dub-apiKey and no Ocp-Apim-Subscription-Key is sent on those calls — a runtime credential carries no account authority (MON-374).

LicensingContextType, the licensing-context shape, carries a required runtimeToken alongside the seat and service-key parts, and no account key.

Checkout is the one place the seller’s account API key appears, and it is always an explicit argument rather than client configuration: createCheckoutSession(request, apiKey), getCheckoutResult(sessionId, apiKey) and pollCheckoutResult(sessionId, { apiKey, signal?, maxAttempts? }). It is a server-side secret — never put it in a browser bundle.

CheckoutSession carries a claimUrl field. It is present only when a free offering was bought against a typed email address: nothing is provisioned until the buyer confirms on that page, so redirect them to it at once (the email carrying the same link is only a fallback). With a returnUrl set they come back with the session id and one getCheckoutResult read is enough; without one, poll.

Note

When catching CryptoError, match on error.name === 'CryptoError' rather than instanceof. The package ships both CommonJS and ESM builds, and a mixed module graph can hold two copies of the class, which breaks instanceof across the boundary — the client’s own internals use the name check for the same reason.

Related

• Node and React quickstart
• Endpoints
• Credentials