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. checkLoginIframe: false
  2. silentCheckSsoRedirectUri: undefined
  3. silentCheckSsoFallback: false
  4. 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 9 days ago

What’s Next