Guest Identity Service (GIS) — Overview

The Guest Identity Service (GIS) provides a public, front-end facing API for user authentication and identity management. It supports legacy email/password authentication flows, social login (Google, Apple, Facebook), and server-to-server business configuration sync.

Base URLs

Please contact your PAR representative to get the Identity Service URLs for staging and/or production.

Authentication

GIS uses two authentication mechanisms:

Mechanism	Description
Client Parameter	A required `client` request body parameter on all auth endpoints. Generated from Punchh Business Dashboard → Whitelabel → Oauth Apps with the scope set to `AdvanceAuth`.
Bearer JWT	A valid JWT access token in the `Authorization` header, required for authenticated endpoints (Sign Out, Change Password).

Token Lifecycle

Access Token — Short-lived JWT used to call resource APIs (e.g., Ordering or Loyalty APIs). Expires per expires_in value (typically 86400 seconds / 24 hours).
Refresh Token — Opaque token used to obtain new access/refresh tokens without re-authentication. Revoked on sign-out or password change.

API Groups

The GIS API is organized into the following groups:

Advanced Authentication

APIs for passwordless authentication using OTP via email or SMS.

Method	Endpoint	Description
`POST`	`/api2/password_less/token`	Send an OTP via email or SMS for passwordless authentication
`POST`	`/api2/password_less/verify`	Verify the OTP token provided by the user
`POST`	`/api2/password_less/refresh_token`	Generate new access and refresh tokens using a refresh token

Auth

Endpoints for user registration, authentication, token management, and session termination.

Method	Endpoint	Description
`POST`	`/api2/basic_auth/signup`	Create a new user via email/password and issue tokens
`POST`	`/api2/basic_auth/signin`	Authenticate with email/password and issue tokens
`POST`	`/api2/refresh_token`	Exchange a refresh token for new access/refresh tokens
`POST`	`/api2/signout`	Revoke refresh tokens and terminate session

Password

Endpoints for password recovery and management.

Method	Endpoint	Description
`POST`	`/api2/basic_auth/forgot_password`	Initiate forgot-password flow (sends reset email)
`POST`	`/api2/basic_auth/reset_password`	Reset password using a one-time token
`POST`	`/api2/basic_auth/change_password`	Change password for an authenticated user
`POST`	`/api/dashboard/change_password`	Change password of a user through the dashboard

Endpoints for social login integrations.

Method	Endpoint	Description
`POST`	`/api2/social/google/signin`	Authenticate using a Google ID token
`POST`	`/api2/social/apple/signin`	Authenticate using an Apple authorization code
`POST`	`/api2/social/facebook/signin`	Authenticate using a Facebook access token

Business Config

Server-to-server endpoint for managing business authentication configuration.

Method	Endpoint	Description
`POST`	`/api/businesses/update_business_config`	Update business authentication flags and configuration

Health

Endpoint for service health monitoring.

Method	Endpoint	Description
`GET`	`/ping`	Liveness probe — verify the service is running

Typical Authentication Flow

Email/Password (Basic Auth)

Signup — Create a new account (POST /api2/basic_auth/signup)
Sign In — Authenticate and receive tokens (POST /api2/basic_auth/signin)
Use Access Token — Call resource APIs with Authorization: Bearer <access_token>
Refresh — When the access token expires, exchange the refresh token (POST /api2/refresh_token)
Sign Out — Revoke tokens and end session (POST /api2/signout)

Obtain Provider Token — Get an ID token (Google), authorization code (Apple), or access token (Facebook) from the provider's SDK
Call Social Sign In — Send the token to the corresponding GIS social endpoint
Receive Tokens — GIS validates the provider token, creates/updates the user, and returns access/refresh tokens
Use Access Token — Same as basic auth flow

Password Recovery

Forgot Password — Request a reset email (POST /api2/basic_auth/forgot_password)
Reset Password — Use the one-time token from the email to set a new password (POST /api2/basic_auth/reset_password)
Sign In — Authenticate with the new password

Iframe SSO

The Signup and Sign In endpoints support an iframe SSO mode:

Set iframe_sso: true in the request body
Provide a redirect_uri that matches one of the OAuth application's configured redirect URIs
The response will contain a single oauth_token instead of the standard access/refresh token pair
Use this token for embedding authentication in iframes

Error Handling

All error responses follow a consistent structure:

{
  "errors": {
    "error_key": ["Human-readable error message."]
  },
  "correlation_id": "c-0c0c0c0c-2222-4ddd-9999-cccccccccccc"
}

errors — Object with error keys mapping to arrays of messages
correlation_id — Include this ID when contacting support for faster diagnostics

Common HTTP Status Codes

Status	Meaning
`200` / `201`	Success
`400`	Missing or invalid parameters
`401`	Invalid or expired credentials
`403`	Account deactivated
`409`	User already exists (signup)
`412`	Precondition failed (auth disabled, invalid client)
`422`	Validation failed (password policy, business rules)
`500`	Internal server error
`503`	Service unavailable

Correlation ID

All endpoints accept an optional X-Correlation-Id request header. When provided, it is echoed back in the response header for end-to-end request tracing. If omitted, GIS generates one automatically.

Note on Downstream APIs

When calling downstream Ordering/Mobile APIs with GIS-issued tokens, integrators may encounter 412 Precondition Failed due to an invalid x-pch-digest. This is not an Identity error — recompute the digest per the downstream API's documentation and retry.

Advanced Authentication