Guide

Frontend Integration

This section provides comprehensive guides for integrating Wink Identity Web into your frontend applications.

Before You Begin

Use this page as a pre-flight checklist before following a stack-specific integration guide.

1) Request credentials

If you do not have your Wink credentials yet (clientId and clientSecret), request them here:

📘

Request Integration Credentials

You can also request access through your onboarding channel or Wink representative.

2) Choose your stack guide

Common Requirements (All Stacks)

Every integration follows the same security model: session-first, server-side secrets, and backend-mediated API calls.

Backend requirements

Your backend must provide internal endpoints that:

  1. Create a Wink session and return a sessionId (for example, GET /session?returnUrl=...&cancelUrl=...).
  2. Retrieve or verify the user profile after authentication (for example, GET /user) using a client token.
⚠️

Never expose clientSecret in frontend code. Never call Wink Session/Verify APIs directly from the browser.

📘

For backend implementation details, see the Backend Integration guide.

Configuration requirements

  • Client-side configuration (browser-safe):
    • clientId, realm, and Wink base/auth URLs
    • Example names: VITE_WINK_CLIENT_ID, VITE_WINK_REALM, VITE_WINK_BASE_URL, VITE_WINK_AUTH_URL
  • Server-side configuration (never exposed):
    • clientSecret and any credentials used to call Wink APIs
  • HTTPS in production is required

Quick Risk Checklist (Read Before Coding)

These are the most common causes of failed integrations.

Whitelist and CORS

  1. Web Origins and Valid Redirect URIs are different settings. Both must be configured in Wink.
  2. Web Origins must not include a trailing slash.
  3. Redirect URI matching is exact by default. For dynamic routes, request /* or use a short callback URL.

CSP

  1. Add Wink hosts (for example https://stageauth.winkapis.com) to your app CSP:
    • connect-src
    • frame-src
    • script-src

A generic "Load failed" after a successful scan is often CSP-related, not CORS.

Required winkInit options (every call)

  1. silentCheckSsoRedirectUri — pass as a full absolute URL if you have the silent-check-sso.html file (e.g. ${window.location.origin}/silent-check-sso.html), or undefined to disable silent SSO entirely.
  2. Explicit redirectUri that matches a whitelisted URL.

checkLoginIframe and silentCheckSsoFallback default to false in [email protected] and no longer need to be passed explicitly.

Flow-specific behavior

  1. OAuth code may return in the URL hash (response_mode=fragment), not query params.
  2. To prevent automatic redirect loops caused by login_session_state, pass disableAutoRedirect: true to winkInit() on pages that should never trigger an automatic redirect (e.g. public landing pages, post-logout screens). Alternatively, clear localStorage.login_session_state manually on mount.
  3. Fetch a fresh sessionId right before the user initiates login and pass it to winkLogin({ sessionId }) — not to the client constructor. This prevents stale sessions when users stay on the page before clicking "Sign in". Never pass sessionId on the callback return leg.
  4. Call winkLogout() only when client.authenticated is true.

Two rules to memorize

  • When calling winkInit(), always pass an explicit redirectUri that matches a whitelisted URL. checkLoginIframe and silentCheckSsoFallback are safe defaults in [email protected] — no extra flags needed.
  • Never read window.location during React render; read it inside useEffect.

Additional Resources

ssdsds

Before You Begin

Use this page as a pre-flight checklist before following a stack-specific integration guide.

1) Request credentials

If you do not have your Wink credentials yet (clientId and clientSecret), request them here:

📘

Request Integration Credentials

You can also request access through your onboarding channel or Wink representative.

2) Choose your stack guide

Common Requirements (All Stacks)

Every integration follows the same security model: session-first, server-side secrets, and backend-mediated API calls.

Backend requirements

Your backend must provide internal endpoints that:

  1. Create a Wink session and return a sessionId (for example, GET /session?returnUrl=...&cancelUrl=...).
  2. Retrieve or verify the user profile after authentication (for example, GET /user) using a client token.
⚠️

Never expose clientSecret in frontend code.
Never call Wink Session/Verify APIs directly from the browser.

📘

For backend implementation details, see the Backend Integration guide.

Configuration requirements

  • Client-side configuration (browser-safe):
    • clientId, realm, and Wink base/auth URLs
    • Example names: VITE_WINK_CLIENT_ID, VITE_WINK_REALM, VITE_WINK_BASE_URL, VITE_WINK_AUTH_URL
  • Server-side configuration (never exposed):
    • clientSecret and any credentials used to call Wink APIs
  • HTTPS in production is required

Quick Risk Checklist (Read Before Coding)

These are the most common causes of failed integrations.

Whitelist and CORS

  1. Web Origins and Valid Redirect URIs are different settings. Both must be configured in Wink.
  2. Web Origins must not include a trailing slash.
  3. Redirect URI matching is exact by default. For dynamic routes, request /* or use a short callback URL.

CSP

  1. Add Wink hosts (for example https://stageauth.winkapis.com) to your app CSP:
    • connect-src
    • frame-src
    • script-src

A generic "Load failed" after a successful scan is often CSP-related, not CORS.

Required winkInit options (every call)

  1. silentCheckSsoRedirectUri — pass as a full absolute URL if you have the silent-check-sso.html file (e.g. ${window.location.origin}/silent-check-sso.html), or undefined to disable silent SSO entirely.
  2. Explicit redirectUri that matches a whitelisted URL.

Flow-specific behavior

  1. OAuth code may return in the URL hash (response_mode=fragment), not query params.
  2. Clear localStorage.login_session_state on mount to avoid redirect loops.
  3. Pass sessionId only on the login-start leg, never on callback return.
  4. Call winkLogout() only when client.authenticated is true.

Two rules to memorize

  • Every winkInit(...) should include the three stability flags plus explicit redirectUri.
  • Never read window.location during React render; read it inside useEffect.

Additional Resources

Updated 11 days ago

What’s Next