JavaScript

CRITICAL SECURITY – READ FIRST

NEVER expose sensitive data in client-side code.

• ❌ clientSecret – server-side only
• ❌ API keys and credentials – server-side only
• ❌ Direct calls to the Wink Session API from the browser – use a backend proxy only

Session creation and any calls that use credentials MUST go through your backend API.

Option A: Use the Vanilla JS Starter Kit (recommended)

The fastest way to integrate is to use the Vanilla JS Starter Kit, which already implements the secure flow (session from backend, no secret in frontend, user profile from backend).

• Repository: wink-identity-vanilla-js-starter-kit
• Stack: Plain HTML, CSS, JavaScript (no bundler)
• Includes: Official Wink login button, get session from backend, get user from backend, logout, silent-check SSO, profile UI

Quick start:

1. Clone the repo and copy config.example.js to config.js.
2. Run a backend (e.g. Wink Identity Backend Templates – Hono, Express, or FastAPI). The frontend needs a backend that exposes GET /session and GET /user.
3. Edit config.js and set:
   • clientId
   • realm
   • baseUrl
   • authUrl
   • backendUrl (your backend URL)
4. Run npx serve . (or any static server).
5. Open the app, click Login with Wink, and complete the flow.

Important: No clientSecret or other credentials are used in the frontend; session creation and user data are done via your backend.

Option B: Add Wink to an existing vanilla JS app

If you prefer to integrate into an existing HTML/JS app instead of using the starter:

Prerequisites

• Static HTML/JS app (or any server-rendered page)
• Node.js or a static file server (e.g. npx serve .)
• A backend API that creates the Wink session and returns user profile (see Backend Integration)

1. Load the SDK

Add the Wink Identity Web SDK via CDN (no build step). For the login button, use the official Wink button styles:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/wink-cloud/wink-integration@main/button.css" />
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/wink-id.umd.min.js"></script>

2. Configuration (client-safe only)

Define config in a config.js file or inline. Never put clientSecret or any secret here.

window.WINK_CONFIG = {
  clientId: "your_client_id",
  realm: "your_realm",
  baseUrl: "https://stagelogin-api.winkapis.com",
  authUrl: "https://stageauth.winkapis.com",
  backendUrl: "http://localhost:8080"
};

Your backend uses credentials and calls the Wink Session API; the frontend only calls your backend (e.g. GET /session, GET /user).

3. Backend contract

Your backend must expose:

• GET /session?returnUrl=...&cancelUrl=... — Creates a Wink session server-side and returns JSON that includes a session id (e.g. sessionId).
• GET /user?clientId=...&token=... — Returns the user profile after authentication.

4. Integration flow

1. On app load: Create a Wink client once with getWinkLoginClient(config) (no sessionId needed here). Call client.winkInit({ silentCheckSsoRedirectUri: '...', onSuccess, onFailure }) to check for an existing session (SSO).
2. On login: Call your backend GET /session?returnUrl=...&cancelUrl=... right before the user initiates login and read the sessionId from the response. Pass it directly to client.winkLogin({ sessionId, redirectUri }) — no need to recreate the client.
3. After auth: Fetch user profile from your backend (GET /user) using the token from the client; do not rely on the client alone for profile.
4. Logout: Call client.winkLogout({ redirectUri }). The SDK handles the full OIDC logout internally, terminates the Wink session, and redirects the user.

For a full reference implementation (config shape, error handling, OIDC logout), use the Vanilla JS Starter Kit as the source of truth.

5. Session ID is mandatory

You must obtain a sessionId from your backend right before the user initiates login and pass it to client.winkLogin({ sessionId }). This ensures the session is always fresh — a session fetched at page load may expire if the user waits before clicking "Sign in". Never call the Wink Session API from the browser.

Security: Your backend calls the Wink Session API with credentials. See Backend Integration and Session Management for details.

6. Token lifetimes (reference)

• Access Token: 5 minutes
• Refresh Token: 30 minutes (each refresh extends all tokens by 5 minutes)
• See Login and Logout Behavior for full token lifecycle.

Configuration (config.js)

All values are client-safe. No clientSecret or credentials in the frontend.

Copy config.example.js to config.js, fill in your values, and never commit config.js with real credentials.

Backend Contract

Your backend must expose:

See Wink Identity Backend Templates for Hono, Express, and FastAPI implementations.

Flow Overview

User clicks "Login with Wink"
    ↓
App calls backend GET /session?returnUrl=...&cancelUrl=...
    ↓
Backend creates Wink session, returns sessionId
    ↓
App calls client.winkLogin({ sessionId, redirectUri })
    ↓
User is redirected to Wink Identity → authenticates (e.g. biometric)
    ↓
Wink redirects back to your app
    ↓
SDK processes callback; onSuccess fires, app fetches user from backend GET /user
    ↓
User is authenticated; call client.winkLogout({ redirectUri }) to sign out

Session ID is Mandatory

You must obtain a sessionId from your backend right before the user initiates login and pass it to client.winkLogin({ sessionId }). Never call the Wink Session API from the browser.

Required inputs when creating a session:

• returnUrl – where to redirect after successful login
• cancelUrl – where to redirect if login is canceled

Required output from backend:

{ "sessionId": "xxxx-xxxx-xxxx" }

Key Points

1. Starter Kit first – Use the Vanilla JS Starter Kit for a complete, secure example.
2. Session from backend – Always get sessionId from your backend right before login and pass it to client.winkLogin({ sessionId }).
3. No secrets in the frontend – No clientSecret; no direct Wink Session API calls from the browser.
4. User profile from backend – After auth, get profile via your backend (GET /user).
5. Logout – Call client.winkLogout({ redirectUri }). The SDK handles the OIDC logout and Wink session termination automatically.

Troubleshooting

Additional Resources

• Vanilla JS Starter Kit
• Backend Templates
• Wink Identity Web SDK (NPM)
• Wink Button Styles