Browser and backend SDK reference

Browser and Node SDK API for application integration. Setup.

Browser options and methods

API	Contract
MixBrowserOptions	issuer, clientId, redirectUri: string; scopes?: string[]
new MixBrowserClient(options)	Issuer normalized without a trailing slash; browser APIs required
signIn(mode = redirect)	redirect navigates away and does not return tokens on that page; popup returns a token-set promise
handleCallback(url = location.href)	Promise of MixTokenSet after matching callback and exchanging the saved transaction
postPopupCallback(url = location.href)	Sends the callback to the opener at the configured origin, then closes the popup
verifyIdentityToken(token, {issuer, audience, nonce})	Promise of verified identity JWTPayload; not access-token authorization

MixTokenSet has access_token, token_type=Bearer and positive expires_in; id_token, refresh_token and scope are optional by type/policy. The current implementation uses a 10-minute stored authorization transaction and a 10-second exchange timeout. State is removed before exchange; a failed one-time exchange requires a fresh authorization attempt, not replaying the code. Popup requires same application origin, user activation and an allowed window; it validates origin/source/state. Redirect and popup need separate integration tests.

The SDK stores the pending verifier/nonce binding in sessionStorage. It does not implement a general token persistence API. Keep tokens out of logs/URLs; select a reviewed in-memory or server-session strategy for your application.

Redirect callback usage

import { MixBrowserClient, type MixTokenSet } from '@zorin/mix-browser';

export function createIdentityClient(clientId: string): MixBrowserClient {
    return new MixBrowserClient({
        issuer: 'https://id.zorin.cloud',
        clientId,
        redirectUri: new URL('/auth/callback', location.origin).href,
        scopes: ['openid', 'profile'],
    });
}

export async function completeRedirect(client: MixBrowserClient): Promise<MixTokenSet> {
    try {
        return await client.handleCallback(location.href);
    } finally {
        const clean = new URL(location.href);
        for (const key of ['code', 'state', 'error', 'error_description']) clean.searchParams.delete(key);
        history.replaceState(null, '', clean.href);
    }
}

The callback path must exactly match the registered application redirect URI. Call client.signIn(‘redirect’) from the login action; call completeRedirect(client) only on the callback route. Render a safe failure state on rejection and offer a new sign-in. The example removes authorization query parameters even on failure; it does not create an app session or implement account linking.

Backend verification

MixVerifierOptions requires issuer and audience; clockTolerance is optional (default 5 seconds), as are expectedTrustTier and expectedIdentityMode. verifyAccessToken(token) checks ES256/JWKS, issuer/audience, required exp/iat/sub/sid/scope, access token_use and valid trust/identity modes; configured expected modes must match. It is offline signature/claim verification, not a session-revocation query. requireScopes(claims, required) rejects missing scopes. bearer(header) expects the Bearer prefix; always pass its result through the verifier.

import { MixTokenVerifier, bearer, type MixAccessClaims } from '@zorin/mix-node';

export function createAccessVerifier(audience: string): MixTokenVerifier {
    return new MixTokenVerifier({
        issuer: 'https://id.zorin.cloud',
        audience,
        expectedIdentityMode: 'MIX_ACCOUNT',
    });
}

export async function verifyRequest(
    verifier: MixTokenVerifier,
    authorization: string | undefined,
    requiredScopes: string[],
): Promise<MixAccessClaims> {
    const claims = await verifier.verifyAccessToken(bearer(authorization));
    verifier.requireScopes(claims, requiredScopes);
    return claims;
}

The audience is the registered audience for this protected API, not a value read from an unverified token. The example deliberately expects MIX_ACCOUNT; organization-directory applications must choose their own intended identity mode. Map verification failure to authentication failure and missing scope/resource permission to authorization failure. Do not log raw tokens. Scope verification is not a resource ownership check.

Trusted gateway helpers

signTrustedIdentity(identity, secret) returns envelope/signature; verifyTrustedIdentity(envelope, signature, secret, options) verifies the HMAC envelope. The identity includes sub, sid, aud, scope[], trustTier, identityMode, expiresAt/issuedAt seconds, requestId, method and path. Secrets need at least 32 bytes; verification bounds the envelope and defaults maxAgeSeconds to 30. Supply expected method/path, check this service’s audience and enforce your replay policy; requestId is not automatically a replay cache. This mechanism is restricted to a trusted gateway/service boundary, not a public arbitrary signing service or RFC 9421 implementation.

The browser/node imports above do not describe React/service packages as fully documented; their separate delivery/reference remains a release condition. Delivery status · OAuth profile. Reviewed 2026-10-17.