Browse Additional Topics

SSO Flow for Web and Mobile

Overview

Punchh offers multiple methods for logging in and signing up loyalty users across POS, online ordering, and mobile app channels. Punchh users are available across all channels, meaning that if a loyalty user is created through your online ordering system, that user is also available for look-up in your POS system and mobile apps, and vice versa.

Point of Sale

You can sign up new users and look up existing users directly at the POS system.

Online Ordering

  • OAuth single sign-on: Sign up and log in users through a Punchh-hosted authentication form for purposes of online ordering loyalty operations. Refer to the OAuth Single Sign-on (SSO) section below for more information.
  • Customers API (online ordering): Sign up and log in users through your authentication form and submit the user credentials to Punchh through the Customers API.
  • Facebook: Log in users through Facebook.
  • Apple: Log in users through Apple IDs.
  • Google: Log in users through Google.

Mobile App

  • OAuth single sign-on: Retrieve the authentication information of a logged-in mobile API user for purposes of authenticating with the online ordering APIs. Refer to the OAuth Single Sign-on (SSO) section below for more information.
  • Users API (mobile): Sign up and log in users through your authentication form and submit the user credentials to Punchh through the Users API.
  • Facebook: Log in users through Facebook.
  • Apple: Log in users through Apple IDs.
  • Google: Log in users through Google.

Punchh Is the Primary Authenticator

In all scenarios, Punchh is recommended as the primary authenticator. If you absolutely must use another system as the primary authenticator and want Punchh loyalty accounts to be secondary to your primary system, then you must use the Customers API or the Users API to create a new user in Punchh based on the users you have in your primary system. You can use whatever password you desire. After creating the user, you will be able to retrieve the new user's account and find the account's authentication token, which you can store and use for future Punchh API operations for that user.

Note: If you set up Punchh as a secondary account as described here, you will not be able to change a user's password or deactivate/reactivate users through the Punchh platform or APIs. Setting Punchh as a secondary authenticator is not a best practice.

OAuth Single Sign-on (SSO)

OAuth SSO is a popular choice for signing up and logging in users who are going through the online ordering process on either a web browser or mobile app. At a high level, this flow involves the following steps.

Note: The Punchh online ordering APIs use the authentication_token available in the user object to authenticate API operations. The Punchh mobile APIs use the access_token available in the user object to authenticate API operations. Therefore, when you are using the online ordering APIs, you typically use the authentication_token in the API calls. The exception to this is when the Punchh platform has been configured to enable generation of access tokens for single sign on. If this setting is enabled, use the access_token for the user in your online ordering authentication instead, just as you would for the mobile APIs. Contact your Punchh representative for more information about this Punchh platform configuration.

The following sections provide more details specific to the OAuth SSO flow for online ordering and mobile.

Web Overview

1. Direct users to the OAuth authorization URL.

2. The user signs up or logs in via the Punchh-hosted authentication form.

3. Upon a successful sign-up or login, the user is directed to your redirect URI, which has been authorized in your Punchh sandbox. Contact your Punchh representative for more information about this Punchh platform configuration.

4. An authorization code is provided as a query string parameter at your redirect URI.

5. Your application uses this authorization code to retrieve an access token from the OAuth Token endpoint.

6. Your application uses the access token from the previous step to retrieve the user.

7. Your application retrieves the authentication_token or access_token specific to the user from the user object. You can then use this token to authorize further online ordering API calls for that user.

Web SSO Flow

Step 1

Direct users to {BASE_URI}/oauth/authorize?client_id={CLIENT_ID}&force_logout=true&redirect_uri=${REDIRECT_URI}&response_type=code&sso=true when they attempt to log in or sign up.

Example:

https://SERVER_NAME_GOES_HERE.punchh.com/oauth/authorize?client_id=CLIENT_ID_GOES_HERE&force_logout=true&redirect_uri=https://example.com&response_type=code&sso=true

Step 2

After the user successfully supplies credentials, the Punchh server redirects the user to your redirect URI, which has been authorized in your Punchh sandbox, with an authorization code. Use the retrieved code in the OAuth Token API endpoint to retrieve the client instance-level access_token:

Request:

curl -X POST \
https://SERVER_NAME_GOES_HERE.punchh.com/oauth/token \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
	"grant_type":"authorization_code",
	"code":"RETRIEVED_CODE_GOES_HERE",
	"client_id":"CLIENT_ID_GOES_HERE",
	"client_secret":"CLIENT_SECRET_GOES_HERE",
	"redirect_uri":"REDIRECT_URI_GOES_HERE"
}'

Response:

{
	"access_token":"ACCESS_TOKEN",
	"token_type":"TOKEN_TYPE",
	"refresh_token":"REFRESH_TOKEN",
	"scope":"SCOPE"
}

Step 3

Use the access_token from the previous step to request the User object from the Users API endpoint. The User object will contain the authentication_token that you can use to authorize future API calls for the user through the online ordering flow, such as updating profile information or processing loyalty redemptions.

Note: If the Punchh platform is configured to enable generation of access tokens for single sign on, retrieve the access_token from the User object instead of the authentication_token. When this setting is enabled, the authentication token will fail to authorize online ordering API calls for the user, so you must use the access token. Contact your Punchh representative for more information about this Punchh platform configuration.

Request:

curl -X GET \
'https://SERVER_NAME_GOES_HERE.punchh.com/api/auth/users?client=CLIENT_ID_GOES_HERE&access_token=RETRIEVED_ACCESS_TOKEN_GOES_HERE' \
-H 'Accept: application/json' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'x-pch-digest:SIGNATURE_GOES_HERE'

Response:

{
	"address_line1": null,
	"anniversary": null,
	"avatar_remote_url": null,
	"birthday": "1927-01-01",
	"city": null,
	"created_at": "2017-12-16T03:23:06Z",
	"email": "test@example.com",
	"email_verified": false,
	"fb_uid": null,
	"first_name": "FIRST_NAME_GOES_HERE",
	"gender": null,
	"id": 111111111,
	"last_name": "LAST_NAME_GOES_HERE",
	"state": null,
	"updated_at": "2018-01-30T06:18:29Z",
	"zip_code": null,
	"allow_multiple": false,
	"authentication_token": "AUTHENTICATION_TOKEN_GOES_HERE",
	"favourite_locations": "",
	"marketing_email_subscription": true,
	"marketing_pn_subscription": true,
	"passcode_configured": false,
	"profile_field_answers": {
		"test": "A",
		"Test1": "Tea",
		"Test2": "Chocolate"
	},
	"referral_code": "REFERRAL_CODE_GOES_HERE",
	"secondary_email": null,
	"terms_and_conditions": false,
	"title": null,
	"user_as_barcode": "1111111",
	"user_as_qrcode": "QR_CODE_GOES_HERE",
	"user_code": "P11111111",
	"user_id": 111111111,
	"user_relations": [],
	"work_zip_code": null,
	"mindbody_client_id": null,
	"preferred_locale": "en",
	"phone": "1111111111",
	"migrate_status": false,
	"email_unsubscribe": false,
	"allow_push_notifications": true,
	"facebook_signup": false,
	"communicable_email": "test@example.com",
	"access_token": null
}

In the response, you will find the authentication_token, which can be used with subsequent online ordering API requests (or the access_token depending on your Punchh platform configuration).

Mobile Overview

1. Direct users to the Order URL configured in your Punchh platform when a user starts the ordering process within the mobile app.

2. The user is already signed in via the app, so the user will not have to sign in again. However, because the online ordering APIs are different from the mobile app APIs, you will have to retrieve the user's authentication information.

3. Generate the security token using the Mobile API /api2/mobile/secure_tokens/ordering and use the Online Ordering SSO API endpoint to convert the security token to an authentication token.

Mobile SSO Flow

Step 1

Send a Punchh Mobile API GET request to the Fetch Client Token API endpoint. The server name must be a mobile base URL https://SERVER_NAME_GOES_HERE.punchh.com/api2/mobile/secure_tokens/ordering. The headers should include the required Mobile User-Agent header. An x-pch-digest (containing the Mobile signature) and Authorization (with a value of Bearer ACCESS_TOKEN_GOES_HERE) header are also required.

Example Request to generate the security_token:

curl -X GET \
https://SERVER_NAME_GOES_HERE.punchh.com/api2/mobile/secure_tokens/ordering \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-pch-digest: MOBILE_SIGNATURE_GOES_HERE' \
-H 'Authorization: Bearer ACCESS_TOKEN_GOES_HERE' \
-H 'User-Agent: AppIdentifier/VersionNumber/BuildNumber(OS_Type)' \
-d '{
	"client": "CLIENT_ID_GOES_HERE"
}'

Example Response to the above request:

{
    "token": "https://example.com?favourite_location_id=111111%2C222222&security_token=SECURITY_TOKEN&source=SOURCE_GOES_HERE"
}

When a mobile user starts the ordering process in the Punchh mobile application, your application needs to redirect the user to the web ordering URL configured in the Punchh platform. Contact your Punchh representative for more information about this Punchh platform configuration.

Step 2

Use the security_token portion from the response above (up to the "&" symbol that's followed by source=SOURCE_GOES_HERE"). Send a POST request to the SSO API endpoint to generate the authentication_token of the user.

Note: If the Punchh platform is configured to enable generation of access tokens for single sign on, retrieve the access_token from the User object instead of the authentication_token. When this setting is enabled, the authentication token will fail to authorize online ordering API calls for the user, so you must use the access token. Contact your Punchh representative for more information about this Punchh platform configuration.

Example Request to generate authentication_token using the security_token value that you generated in step 1:

curl -X POST \
https://SERVER_NAME_GOES_HERE.punchh.com/api/auth/sso \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-pch-digest: SIGNATURE_GOES_HERE' \
-H 'User-Agent: Punchh/OnlineOrder/1.0/Web/BrowserVersion/OS_Type' \
-d '{
	"client":"CLIENT_ID_GOES_HERE",
	"security_token": "SECURITY_TOKEN_GOES_HERE"
}'

Example Response to the above request:

{
  "token": {
	"access_token":"ACCESS_TOKEN_GOES_HERE"
	},
	"user": {
		"anniversary":null,
		"avatar_remote_url":null,
		"birthday":null,
		"created_at":"2015-08-18T13:53:06Z",
		"email":"test@example.com",
		"fb_uid":"FB_UID_GOES_HERE",
		"first_name":"FIRST_NAME_GOES_HERE",
		"gender":null,
		"id":111111111,
		"last_name":"LAST_NAME_GOES_HERE",
		"updated_at":"2015-08-18T13:53:06Z",
		"allow_multiple":false,
		"authentication_token":"AUTHENTICATION_TOKEN_GOES_HERE",
		"favourite_locations":"",
		"preferred_menu_items":[],
		"referral_code":"REFERRAL_CODE_GOES_HERE",
		"referral_path":"URL_GOES_HERE",
		"secondary_email":null,
		"user_as_barcode":"1111111",
		"user_as_qrcode":"QR_CODE_GOES_HERE",
		"user_relations":[],
		"wants_menu_notifications":false,
		"profile_field_answers":{},
		"address_line1":null,
		"zip_code":null,
		"phone":null,
		"migrate_status":false,
		"work_zip_code":null,
		"email_unsubscribe":null,
		"allow_push_notifications":true,
		"facebook_signup":false,
		"communicable_email":"test@example.com",
		"access_token":null
	}
}

In the response, you will find the authentication_token, which can be used with subsequent API requests (or the access_token depending on your Punchh platform configuration).

Copyright © 2025 PAR Technology Corporation. All rights reserved.
PAR Technology Corporation 8383 Seneca Turnpike, Suite 3 New Hartford, New York 13413 (315) 738-0600 legal@partech.com. PAR Tech is a leading global provider of software, systems, and service solutions to the restaurant and retail industries.
You may learn about its product offerings here.
Before using this application, please read the Limited License Agreement and the PAR Tech Terms of Use.
Previous
Generating x-pch-digest Header for Online Ordering APIs
Next
How To Send Menu Items to Punchh