Module 2: Sign-in

Previous Topic	Next Topic
Online Ordering Module 1b: Complete Sign-up for a POS "Dummy" Account	Online Ordering Module 3a: Show Offers in Guest Account

Goal

Prerequisites

You must have read the Online Ordering Module 1a: Create User and Online Ordering Module 1b: Complete Sign-up for a POS "Dummy" Account tutorials.

Use Cases and Context

Most API calls in online ordering and mobile require the user’s token: access_token. For online ordering, when the user signs in, the access token is returned in the API response, and the token is needed for most other online ordering API calls to perform actions on behalf of the user. If the user does not log in, the access token cannot be retrieved and subsequent API calls cannot be authenticated.

Note: You may pass access_token instead of authentication_token in the authorization header of online ordering endpoints. It will be passed as a bearer token (e.g., Authorization: Bearer {{access_token_goes_here}})

Applicable API Endpoints


Endpoint Name/Path	Relevant Request Parameters	Relevant Response Parameters
Log in With Email and Password POST {server-name}/api/auth/customers/sign_in	client The following parameters shown under the User object must be provided: - email - password	access_token Other useful user profile parameters: - address_line1 - birthday - city - email - first_name - last_name - state - zip_code - favourite_locations - marketing_email_subscription - phone

Example Code

curl --location --request POST 'https://SERVER_NAME_GOES_HERE.punchh.com/api/auth/customers/sign_in' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-pch-digest: SIGNATURE_GOES_HERE' \
--header 'User-Agent: Punchh/OnlineOrder/1.0/Web/BrowserVersion/OS_Type' \
--data-raw '{
    "client": "CLIENT_GOES_HERE",
    "user": {
      "email": "test@example.com",
      "password": "PASSWORD_GOES_HERE"
    }
}'

import json
from http_client import send_request

def sign_in():
  path = "/api/auth/customers/sign_in"
  http_verb = "POST"
  body = json.dumps({
    "client": "CLIENT_GOES_HERE",
    "user": {
      "email": "test@example.com",
      "password": "PASSWORD_GOES_HERE"
    }
  })
  response = send_request(path, http_verb, body)
  print(f"Response: {response}")

sign_in()

class SignIn
  require_relative 'generate_signature.rb'
  require_relative 'http_client.rb'
  require 'json'

  # Client for the environment that you are pointing the request to
  CLIENT = "CLIENT_GOES_HERE"
  PATH = "/api/auth/customers/sign_in"
  HTTP_VERB = "POST"

  def self.sign_in
    body = {client: CLIENT, user: {email: "test@example.com", password: "PASSWORD_GOES_HERE"}}.to_json
    response = HttpClient::send_request(PATH, HTTP_VERB, body)
  end
end

SignIn.sign_in

Workflow

The user’s email address and password must be passed as parameters in the request of the Log in With Email and Password online ordering API endpoint, and the user’s acess token is returned in the response of that API call. This access token will be used to authenticate subsequent online ordering API calls made for that user. For example, the value of the access_token parameter returned in the response of the Log in With Email and Password API must be provided as the value of the access_token request parameter when making a call to the Fetch Account Balance of User online ordering API endpoint.

If the Punchh platform is configured to enable generation of access tokens for single sign on, the access_token parameter can be returned in the response of the Log in With Email and Password API. In mobile API endpoints, the value of the access_token parameter is used as the value of the Authorization header where required.

Best Practices

Be sure to review the "Best Practices" section in the Online Ordering Module 1a: Create User tutorial.
If you are building a third-party application and will be using the /auth/ endpoints to sign up / sign in users, then it is best practice to enable the Enable Generation of Access Tokens for Single Sign On? option and use the access_token instead of authentication_token for all subsequent calls. Additionally, if you are using a third-party IDP (Azure, AWS Cognito, etc.), you will have to use access_token to authenticate all calls. For details, see Loyalty Guest Authentication Using a Third-Party IDP. Note: You must log in to the developer portal to view this page.
Parameters returned in the response of the Log in With Email and Password API can be used to display relevant user profile information. For example, first_name and last_name are commonly used on a website to greet the user by name. Other parameters can be used to display the current value on an edit profile page (e.g., address_line1, birthday, city, email, state, zip_code, favourite_locations, marketing_email_subscription, and phone).

Online Ordering API Certification Tutorial - Module 2: Sign-in