Web SDK

Install

The Web SDK ships from npm.

pnpm add wink-identity-sdk
# or
npm install wink-identity-sdk
# or
yarn add wink-identity-sdk

It's a tiny ESM module — no peer deps. Use it in any modern bundler (Next.js, Vite, Remix, plain Webpack).

Configure

The SDK exports a getWinkLoginClient(config) factory that returns a Keycloak-style client. Build the config from environment variables your merchant dashboard issued:

export const getWinkConfig = (sessionId?: string) => {
  const config = {
    clientId:           process.env.NEXT_PUBLIC_WINK_CLIENT_ID!,
    realm:              process.env.NEXT_PUBLIC_WINK_REALM!,
    loggingEnabled:     true,
    cancelUrl:          `${window.location.origin}/callback`,
    onAuthErrorFailure: (e: unknown) => console.error("Wink auth error:", e),
    override:           true,
    overrideValues: {
      // Stage hosts — what every external developer's keys point at.
      BASE_URL: "https://stagelogin-api.winkapis.com",
      AUTH_URL: "https://stagelogin-api.winkapis.com/auth",
    },
  };
  if (sessionId) config.sessionId = sessionId;
  return config;
};

Start a login

Logging in is a two-step pas-de-deux: your backend mints a sessionId from the Wink Core API, then the SDK redirects the browser into Wink's hosted capture flow with that session as state. Don't try to skip the backend session step — anonymous calls fail.

1. Mint a sessionId on your backend

   Hit POST /wink/v1/session from your server with merchant Basic auth. The response contains sessionId — surface it to the browser via your own API endpoint.

2. Pass the sessionId into the SDK and call winkInit

   TypeScript web/components/WinkAuthProvider.tsx

   const login = async () => {
     const sessionId = await fetchSessionFromBackend("/api/wink/session");
   
     const client = getWinkLoginClient(getWinkConfig(sessionId));
   
     client.winkInit({
       onLoad: "login-required",
       checkLoginIframe: false,         // always — see Gotcha #2
       onFailure(error) {
         console.error(error);
       },
     });
   };

   The SDK redirects the browser to Wink's hosted capture flow. The user enrols or authenticates, then bounces back to your cancelUrl with an authorization code in the URL fragment.

Handle the callback

On return, the SDK has a separate code path for redeeming the authorization code. Critical: only call winkInit when a code is actually present in the URL — calling it on every mount produces redirect loops (see Gotcha #1).

useEffect(() => {
  const client = getWinkLoginClient(getWinkConfig());  // no sessionId on return

  // OAuth code can land in either the query string or the hash fragment.
  const haveCode = /[?#&]code=/.test(window.location.search) ||
                   /[?#&]code=/.test(window.location.hash);

  if (!haveCode) return;  // fresh load — idle

  client.winkInit({
    checkLoginIframe: false,
    onSuccess() {
      const token = (client as any).token;
      // hydrate user profile via your backend, set authenticated state
    },
    onFailure(error) {
      console.error("winkInit onFailure:", error);
    },
  });
}, []);

Logout

Call winkLogout to end the merchant OIDC session. Note that this does not end the underlying Wink realm SSO cookie — see Gotcha #5.

const logout = async () => {
  if ((client as any).authenticated) {
    await client.winkLogout({
      redirectUri: window.location.origin,
    });
    return;  // winkLogout redirects; nothing more to do
  }
  // Local-only sign-out fallback
  window.location.assign(window.location.origin);
};

Gotchas

Eight things WinkKey paid for in integration time. Front-load these — most show up only on iPhone Safari or in production Keycloak configurations, so they're easy to miss in dev.