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://unpkg.com/[email protected]/dist/wink-id.umd.js"></script>

Alternative (jsDelivr for SDK):

<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.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 with getWinkLoginClient(config) (no sessionId). Call client.winkInit({ silentCheckSsoRedirectUri: '...', onSuccess, onFailure }) to check for an existing session (SSO).
2. On login: Call your backend GET /session?returnUrl=...&cancelUrl=..., read the session id from the response, then create a new client with that sessionId in config: getWinkLoginClient({ ...config, sessionId }). Call client.winkInit({ onLoad: 'login-required', checkLoginIframe: false, onFailure }) to trigger the login redirect.
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: Build the OIDC logout URL (authUrl + realm + logout endpoint + post_logout_redirect_uri + client_id + optional id_token_hint), then redirect the user. Clear local tokens/cookies as needed.

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 before starting the login flow and pass it in the client config when creating the Wink client (so the SDK can add it to the authorization URL). 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 creates Wink client with sessionId in config
    ↓
App calls winkInit({ onLoad: "login-required", ... })
    ↓
User is redirected to Wink Identity → authenticates (e.g. biometric)
    ↓
Wink redirects back to your app
    ↓
SDK processes callback; onSuccess, app fetches user from backend GET /user
    ↓
User is authenticated; use OIDC logout URL for sign out

Session ID is Mandatory

You must obtain a sessionId from your backend before starting the login flow and pass it in the client config when creating the Wink client. 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; pass it in the client config when starting login.
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 – Use the OIDC end-session URL with id_token_hint and post_logout_redirect_uri.

Troubleshooting

Additional Resources

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