Session Creation Flow

Developer's Frontend
    ↓
Calls Backend API (/api/wink/session)
    ↓
Developer's Backend
    ↓
Calls Wink Session API (with credentials)
    ↓
Wink Backend
    ↓
Returns sessionId
    ↓
Developer's Backend
    ↓
Returns sessionId to Frontend
    ↓
Frontend includes sessionId in authorization URL

🔒

CRITICAL SECURITY:

• Session creation MUST be done server-side
• NEVER call the Wink Session API directly from the browser
• NEVER expose clientSecret or credentials in client-side code
• Always use a backend API endpoint as a proxy

Session ID Usage

Once you have the sessionId from your backend, pass it directly to winkLogin() at the moment the user initiates login. The SDK will automatically include the sessionId in the authorization URL.

Important: Fetch a fresh sessionId right before calling winkLogin() — not at page load. If the user stays on the page for a while before clicking "Sign in", a session fetched earlier may have already expired.

1. Get the sessionId from your backend

Example request to your backend:

const session = await fetch(
  "/api/wink/session?" +
    new URLSearchParams({ returnUrl, cancelUrl })
).then((r) => r.json());

const sessionId = session.sessionId;

2. Pass the sessionId to winkLogin()

// Create the client once at startup (no sessionId needed here)
const client = getWinkLoginClient({ clientId, realm, cancelUrl, ... });

// When the user clicks "Sign in", fetch a fresh session and pass it at login time
await client.winkLogin({
  sessionId,
  redirectUri: returnUrl,
  ...
});

The SDK will automatically attach the sessionId to the authorization request.

📘

See: Backend Integration - Session Creation API for endpoint details.