CredentialProvider

Provides authentication credentials to the SDK.

Implementors are responsible for:

Obtaining credentials (e.g. via API calls, user login flows, or third-party auth services).
Returning a valid SDKCredential with either a token or authorizationState.
Setting expiry_at when the credential has a known expiration so the SDK can schedule refresh.
Handling errors and never leaking sensitive data through error messages.

The SDK owns the credential lifecycle: it calls authenticate once during initialization and, if refresh is provided and expiry_at is set, schedules automatic refresh before expiry.

Refresh precedence

The SDK selects exactly one refresh mechanism per session, evaluated at connect time (and re-evaluated on reconnect):

`refresh` provided	SAT carries `sat:refresh` scope	Active mechanism
yes	yes	Client Bound SAT (DPoP, internal)
yes	no	Developer-provided `refresh()`
no	yes	Client Bound SAT (DPoP, internal)
no	no	None — session ends at `expiry_at`

When the SDK falls back to the developer-provided refresh() because the SAT lacked sat:refresh scope, a credential_refresh_fallback event is emitted on SignalWire.warnings$ so application code can observe the transition.

Mint a SAT via POST /api/fabric/subscribers/tokens with fingerprint and scope: ["sat:refresh"] (both currently optional on that endpoint) to enable the Client Bound SAT path; otherwise provide refresh() here.

Properties

refresh

() => Promise<SDKCredential>

Obtains fresh credentials before the current ones expire. Optional. Implementor responsibilities: - Resolve with a new SDKCredential containing an updated token (or authorizationState) and expiry_at. - Reject (throw) if refresh is not possible — the SDK will stop the refresh schedule. SDK behavior: - Never called for a Client Bound session (a SAT that carries sat:refresh scope); the SDK refreshes internally instead. See the precedence table above. - Scheduled automatically before expiry when expiry_at was set on the previous credential; implementors do not need to manage timing. - Also called outside the schedule: before a reconnect when the credential has passed its expiry_at, and when SignalWire refuses the current SAT on connect, on a reconnect, or on a request. - On rejection, the refresh schedule stops and the session continues with the current credentials until they expire.

Methods

authenticate()

authenticate(context?): Promise<SDKCredential>

Obtains credentials. Called during client initialization. For a Client Bound session, the SDK calls it again to get a fresh SAT before each reconnect that can’t resume the previous session, and when SignalWire refuses the current SAT on connect or on a request. Those calls happen in the background, with no user action to trigger them.

Implementor responsibilities:

Resolve with a valid SDKCredential on success.
Reject (throw) on failure — this will cause client initialization to fail.
When context.fingerprint is provided, forward it to the server-side token endpoint with scope: "sat:refresh" to enable automatic token refresh. Ignoring context.fingerprint causes the SDK to fall back to refresh() (if provided) or end the session at expiry.

SDK behavior:

Awaits this method before establishing the WebSocket connection.
On rejection, propagates the error to the caller of SignalWire().

Parameters

context

AuthenticateContext

Authentication context provided by the SDK at credential-request time. See AuthenticateContext.

Returns

Promise<SDKCredential>