🔑 Before You Begin - Request Your Credentials

If you have not yet received your ClientID and Secret Key, you can request access here:

📘

Request Integration Credentials

Contact your Wink representative or submit a request through your onboarding link.

Your backend is responsible for:

1. Session Creation: Creating Wink sessions and returning sessionId
2. Token Validation: Validating tokens received from the frontend

Session Creation API

Endpoint: POST https://api.winklogin.com/wink/v1/session

Authentication: Basic Authentication

• Username: Your clientId
• Password: Your clientSecret

Request Headers:

Content-Type: application/json
Authorization: Basic <base64(clientId:clientSecret)>

Request Body:

{
  "returnUrl": "https://your-app.com/api/auth/callback/keycloak",
  "cancelUrl": "https://your-app.com/signin?error=access_denied"
}

Response:

{
  "sessionId": "wink-session-id-here"
}

Error Responses:

• 400 Bad Request: Invalid request body (missing returnUrl or cancelUrl)
• 401 Unauthorized: Invalid credentials
• 500 Internal Server Error: Server error

🔒

SECURITY:

• NEVER expose clientSecret in client-side code
• ALWAYS use Basic Authentication with clientId:clientSecret
• ALWAYS call this API from your backend, never from the browser

📘

Implementation: Your backend should create an endpoint (e.g., /api/wink/session) that:

1. Receives returnUrl and cancelUrl from the frontend
2. Calls the Wink Session API with Basic Authentication
3. Returns the sessionId to the frontend

Token Validation

Your backend must validate these tokens to securely establish the user session, authorize access to protected resources, and prevent tampering or token misuse.

This section describes how to validate tokens, how to retrieve user identity information, and how to correctly implement the server-side logic required to integrate with the Wink Identity platform.

Validating Access Token

After the Wink Identity Web SDK completes authentication in the browser and redirects the user back to your application, your frontend must send the Access Token to your backend.

Your server should then validate this token against the Wink Identity Verification API.

Verify Client API endpoint

Validate the Access Token and retrieve the user’s clear-profile data:

POST https://stage-api.winklogin.com/api/ConfidentialClient/verify-client

📘

See API Reference for details on how to use this API.

👍

Note that success depends on

a) Access Token azp claim matches your clientid
b) ClientID is properly setup in Wink
c) Secret Key is correct and matches your ClientID
d) Token is not expired

If API response is OK, a JSON object will be returned containing clear user data that will look like this

{
  "firstName": "test",
  "lastName": "test",
  "contactNo": "(875) 945-3854",
  "email": "[email protected]",
  "winkTag": ";stage-t",
  "winkToken": "4b15e1bc-d098-4555-bd12-4e904775a413",
  "dateOfBirth": "**/**/1983",
  "expiryTime": "2023-03-22T17:43:22Z"
}

Example Code

The following code block is an example on how to use the Verify_Client API endpoint in your code to validate the token, receive clear information about the user and display it. In reality, you can use the user profile to identify the user who has logged in and proceed with your normal workflow of your app.

🚧

Note the below code is an example shown for Client side but it's critical that the same code be actually developed on the back end server. It's not advisable to expose the secret key on client side code. The below code should be just used as a reference to see how to verify the token and detokenize it

function validateToken() {
        console.log('validateToken');
        const token = winkLoginClient.token;
        //  $("#wink-oauth-validatetoken-button").click(function (e) {
        const  clientId  = 'your_clientid'; 
        const secret = 'your_secret';
        const url = 'https://stage-api.winkapis.com/api/ConfidentialClient/verify-client';

        var formData = {
          ClientId: clientId,
          AccessToken: token,
          ClientSecret: secret,
        };
        console.log(formData);
        //Array
        $.ajax({
          contentType: 'application/json',
          type: 'POST',
          url,
          data: JSON.stringify(formData),
          dataType: 'json',

          success: function (result, status, xhr) {
            var table = $('<table><tr><th>Profile Details</th></tr>');
            table.append('<tr></tr>');
            table.append('<tr><td>FirstName:</td><td>' + result['firstName'] + '</td></tr>');
            table.append('<tr><td>LastName:</td><td>' + result['lastName'] + '</td></tr>');
            table.append('<tr><td>ContactNo:</td><td>' + result['contactNo'] + '</td></tr>');
            table.append('<tr><td>Email:</td><td>' + result['email'] + '</td></tr>');
            table.append('<tr><td>WinkTag:</td><td>' + result['winkTag'] + '</td></tr>');
            table.append('<tr><td>WinkToken:</td><td>' + result['winkToken'] + '</td></tr>');
            table.append('<tr><td>ExpiryTime:</td><td>' + result['expiryTime'] + '</td></tr>');
            //$("#tBody").empty();
            $('#tBody').append(table);
          },
          error: function (xhr, status, error) {
            alert('Result: ' + status + ' ' + error + ' ' + xhr.status + ' ' + xhr.statusText);
            console.error(error);
          },
        });
        //disable
        $('#wink-oauth-validatetoken-button').disabled = true;
        document.getElementById('wink-oauth-validatetoken-button').disabled = true;
}

👍

Handling the UserID in your app and system

The WinkToken which is present in the sub claim of Access_Token and ID_Tokens will represent the unique ID of the user who logged in. This ID is unique to the user for your clientId in the Wink ecosystem.

Note the tokens also contain a username for the user called the WinkTag in the preferred_username claim. This information is optional for your application to use ( can be mapped against the username established for this user in your system ). This username is unique to the user in the entire Wink ecosystem across all ClientIDs.