Advanced Authentication

Overview

Punchh now supports Advanced Authentication for user login on both web and mobile applications. These APIs are designed to provide secure, efficient, and user-friendly login experiences. It ensures high security while offering a smooth user experience, making it perfect for applications that require reliable user verification.

Note: Advanced Authentication supports both web and mobile platforms. Therefore, these APIs can be used to access both Online Ordering and Mobile APIs.

Authentication Options

Advanced Authentication supports OTP (One-Time Password) through email or SMS to enhance security and user convenience.

Features and Benefits of Advanced Authentication

Features

Dual Communication Channels - Advanced Authentication supports both email and SMS for sending authentication codes, depending on the brand’s configuration. This dual-channel approach ensures users can access authentication codes across devices and platforms, even if they have limited access to one communication channel.

Validation Method - Currently, Advanced Authentication supports OTP as the validation method.

• OTP (One-Time Password): Users receive a temporary, single-use password via email or SMS based on the user's selection. It adds an extra layer of security to the authentication process.

Easy Integration - The Advanced Authentication platform offers simple APIs for easy integration with existing applications, reducing development time.

Customizable Authentication Flows - Developers can customize authentication workflows according to the specific needs of their application.

Security and Compliance - Advanced Authentication uses strong encryption and security protocols to protect all communications and user data, helping meet regulatory standards like GDPR (General Data Protection Regulation) and CCPA (California Consumer Privacy Act).

Cross-Platform Support - Advanced Authentication supports both web and mobile platforms, allowing users to authenticate on any device.

Benefits

Enhanced User Experience - Businesses can choose between email or SMS, making the login process smoother and more user-friendly for their users. These methods also eliminate the need for passwords, reducing friction and improving the login experience.

Increased Security - OTP provides strong protection against unauthorized access, reducing the risk of security breaches, including phishing and credential-stuffing attacks.

Improved Accessibility - By offering authentication via both email and SMS, Advanced Authentication ensures users can log in regardless of their location or device. This approach caters to those with limited access to one channel.

Scalable for Business Growth - Flexible workflows and easy integration make Advanced Authentication easy to scale and adapt as your business grows, without needing significant system changes.

Compliance and Trust - The Advanced Authentication platform adheres to global security and privacy standards, building trust with users and ensuring their data is protected.

Getting Started With Advanced Authentication

To start using Advanced Authentication:

1. Get your API key - Use a valid OAuth client key from the Punchh platform to send requests to the API endpoints. Ensure the OAuth app you create has the Auth Service scope selected.

2. Use HTTPS - The API accepts only secure HTTPS connections. Any HTTP requests will be redirected to the corresponding HTTPS resources.

3. Monitor API responses - The API sends responses in JSON format. If an API request returns an error, it will be included in the JSON response with an "error" key.

PKCE Flow

PKCE (Proof Key for Code Exchange) adds extra security to the OAuth 2.0 process. It prevents attacks by ensuring that only the client application that requested the authorization code can exchange it for an access token. In PKCE, the code_challenge is used during the OAuth 2.0 authorization process to add extra security. It helps prevent attacks like intercepting authorization codes, especially in cases where apps (like mobile apps or single-page applications) cannot securely store a client secret.

How PKCE Works

1. Generate a Code Verifier - The client application (e.g., a mobile app) creates a random string called the code_verifier. This string is usually made to be very random and difficult to guess, like a complex password generated by a secure tool.

2. Create a Code Challenge - The client application generates a code_challenge from the code_verifier using a method like SHA-256 hashing. The code_challenge is a hashed version of the code_verifier and is used to verify the request. If SHA-256 is used, the code_challenge is the base64url-encoded SHA-256 hash of the code_verifier.

Here is a JavaScript code snippet that can be used as a pre-request script for Postman to generate the code_verifier and code_challenge. Both the code_verifier and code_challenge are saved to the environment variables once this script executes.

function generateCodeVerifier(length) {
    const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
    let codeVerifier = '';
    const charactersLength = characters.length;
    for (let i = 0; i < length; i++) {
        codeVerifier += characters.charAt(Math.floor(Math.random() * charactersLength));
    }
    return codeVerifier;
}

function generateCodeChallenge(codeVerifier) {
    var hash = require('crypto-js') .SHA256(codeVerifier);
    var base64Hash = hash.toString(require('crypto-js') .enc.Base64);
    var base64UrlHash = base64Hash.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
    return base64UrlHash;
}

var rand = pm.variables.replaceIn('{{$randomInt}}{{$randomInt}}{{$randomInt}}');
var raw_body = pm.request.body.raw 
raw_body = raw_body.replaceAll(/\\"|"(?:\\"|[^"])*"|(\/\/.*|\/\*[\s\S]*?\*\/)/g, (m, g) => g ? "" : m).trim();
raw_body = raw_body.replaceAll('{{rand}}', rand);
var code_verifier = generateCodeVerifier(32);
var code_challenge = generateCodeChallenge(code_verifier);

raw_body = raw_body.replaceAll('{{codeChallenge}}', code_challenge);

pm.request.body.raw = raw_body

console.log("Raw Body : " + raw_body)
var jsonData = JSON.parse(raw_body)
pm.environment.set("email", jsonData.email);

pm.environment.set("codeVerifier", code_verifier);
pm.environment.set("codeChallenge", code_challenge);
console.log("Code Challenge : " + code_challenge)
console.log("Code Verifier : " + code_verifier)

3. Send OTP - The vendor includes the code_challenge in the Send OTP API request to the Punchh server. The code_verifier is not sent at this stage.

4. Receive Authorization Code - After successful authentication, the Punchh server returns an authorization code to the vendor as in standard OAuth 2.0.

5. Exchange Code for Token - When the vendor exchanges the authorization code for an access token, it also sends the original code_verifier with the request.

6. Validate Code Verifier - Punchh verifies the code_verifier by applying the same transformation (e.g., SHA-256 hashing) and checks it against the original code_challenge received during the authorization request in Step 3. If they match, the access token is issued.

Why Is PKCE Important?

The code_challenge and code_verifier process ensures that only the vendor that initiated the authorization request can use the authorization code to get an access token. PKCE ensures that even if someone intercepts the authorization code, they cannot use it without the correct code_verifier, which only the legitimate vendor knows. This adds an extra layer of security to the authorization process.

Advanced Authentication API Endpoints

You can integrate Advanced Authentication APIs into your application to handle user authentication.

Access Punchh APIs Using Access and ID Tokens

The Verify Token API returns an access_token and an id_token in the response after OTP verification. The id_token is used to identify the user, while the access_token is used to authorize access to Punchh APIs.

When the user authenticates using Advanced Authentication, you must include both tokens in the headers of API requests that require an Authorization header when accessing the Punchh Mobile and Online Ordering APIs.

In these API requests:

• The id-token header should contain the id_token value.
• The Authorization header should contain the access_token value and must be supplied in the format: Bearer ACCESS_TOKEN_GOES_HERE.

When you use the Refresh Token API after a token has expired, you should include the new access_token and id_token values in the Authorization and id-token headers, respectively, in your subsequent API requests.

The cURL request example shows how the access_token and id_token are included in the Authorization and id-token headers, respectively, in the Fetch User Balance Mobile API.

curl --request GET \  
--url https://server_name_goes_here.punchh.com/api2/mobile/users/balance \  
--header 'Accept: application/json' \  
--header 'Accept-Language: ' \  
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjB4d3RBV2E0NkhNTi10RVX1...' \  
--header 'id-token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjB4d3RBV2E0NkhNTi10RVRjX1k4cCJ9eyJua...'\
--header 'Content-Type: application/json' \  
--header 'User-Agent: AppName/AppVersion/BuildNumber (OS; Model; MANUFACTURER; MODEL; OS Version)' \
--header 'x-pch-digest: {{$$.env.signature}}'