PunchTab Developer API

PunchTab is dedicated to provide all the tools to build loyalty around your website, application or product.

Authentication:

In order to build loyalty into your application, you will need to identify and authenticate your loyal users. PunchTab provides multiple ways to authenticate a user as a member of a program. If you don't have an existing authentication layer, or do not want to integrate/leverage your existing authentication system, then we provide our own social login, and email/password login. If you do want to integrate with your existing authentication system, PunchTab can piggy-back on it with our SSO option, so users don't have to create a loyalty account.


Social Login

PunchTab provides social login by default with all programs. The flow works as follow:

User will be prompted to connect or login when loading the loyalty program. Then they will be prompted by the social network provider's permission popup. User can connect/login button, or create an account.

If you have an Expand plan, you can configure PunchTab to use which app the user connects to in order to create the account thanks to our "whitelabeling feature".


Email/Password login

PunchTab also provides a way for the user to signup and sign in just with their email address. This feature is available based on the account you have (see available features), and configurable from the admin interface.


Using Single Sign-On(SSO) API

SSO allows your users who are already authenticated on your site or application, to seemlessly log in to PunchTab loyalty program platform automatically without having to create an account and log in again. SSO is a feature available our Expand customers. Given below are API's to support SSO:

The login flow with SSO has 3 steps, this document will guide you through each step:

Checking the login status of a member

Endpoint:  
URL
https://api.punchtab.com/v1/auth/status
HTTP method GET
Parameters:  
token authResponse.accessToken from login API
Access key Access Key from your developer page
Response:
status "connected" if token is valid otherwise "disconnected"

Logging in user:

Member account will be created if it doesn't exist, the email address is used as the key to check for existence.

Endpoint:  
URL
https://api.punchtab.com/v1/auth/sso
HTTP method POST
Parameters:  
client_id Client Id from your developer page
Access key Access Key from your developer page
auth_request a base64 encoded string which contains a unique identifier for the user, the first name, last name, email address and optionnally a link to his avatar and coutry code.
timestamp Unix timestamp (seconds elapsed since Unix epoch), should match valued used to generate signature below.
signature HMAC_SHA1 of auth_request and timestamp above
Response:
status "connected" for successful login. Other values are "disconnected", "not_authenticated" and "not_authorized"
authResponse.accessToken Authentication token for this user to be used for subsequent API calls returned only if status is ‘connected’
authResponse.expiresIn Number of seconds until token expires

Examples: Given below are examples in different languages on how to generate parameters for SSO API. You can use any libraries such as curl to make the REST API call by passing these parameters.

  • Using Python

  • Using PHP

  • Using HTML and JavaScript (client side implementation)

    If you want to implement SSO without backend REST integration, you can leverage SSO on top of an existing loyalty program. You just need a valid program running on your page web page. Then, generate SSO API parameters client_id, auth_request, timestamp and signature(details given above) as you would for the REST API and place it in a JavaScript variable as given below either in the HEAD or beginning of BODY of your site.

Logging out user:

Endpoint:  
URL
https://api.punchtab.com/v1/auth/logout
HTTP method GET & POST
Parameters:  
token authResponse.accessToken from login API
Access key Access Key from your developer page
Response:
status "disconnected" for successful logout