SSO Accounts Synchronization

Many brands already have a customer base, or sign their customers in through one identity provider that also serves loyalty and other systems. Token exchange lets those customers use the full API — saved cards, addresses, account settings — without creating a separate PAR Ordering login.

Prefer PAR Guest Identity. For a brand that authenticates customers outside PAR Ordering, the preferred setup today is PAR Guest Identity: the customer signs in through it and the token it issues goes straight on the Authorization header, with no exchange step. Ask your Integration Manager whether the brand is on Guest Identity before building the flow on this page. The STS token exchange described here remains available for brands that are not.

Before you start you need:

  • A customer access_token from your identity provider, and an endpoint on your side that returns the customer's profile for it (see below)
  • A client_id and client_secret from PAR Ordering for the server-to-server authentication

Customer Info Endpoint

To register and update customers, expose a /customer-info endpoint on your side. PAR Ordering calls it with the customer's access_token and reads the profile it returns:

Request

{
  "customer_account_uuid": "1df3d3b3-d2b6-4126-93f2-1fdbd419268b"
}

Response

{
  "customer_account_uuid": "1df3d3b3-d2b6-4126-93f2-1fdbd419268b",
  "first_name":"John",
  "last_name": "Doe",
  "email": "john.doe@mail.com",
  "phone_number": "+23533674523"
}

Register/Login to PAR Ordering

Registration and sign-in are one flow, so your app never needs to know whether the customer already has a PAR Ordering account. If they do, they are signed in; if not, the account is created first. Either way you get back a PAR Ordering customer token (token.value) for the protected resources.

The diagram shows the sequence:

SSO-Auth-Flow.jpg

Authentication with identity provider

Your app signs the customer in with your identity provider and holds on to the access_token it gets back. That is the token you will exchange.

M2M Authentication with PAR Ordering

Next, authenticate your server to PAR Ordering. Exchange the client_id and client_secret your Integration Manager issued for a client token at POST /oauth/tokens — see Ordering API Client for the details.

Request

Attribute Type Example Value Description
Application Header Application Key "f3a90488ffee32c3acb6fcd0ca417cf6" Specific Management Center application key provided by PAR Ordering
Authorization Header "Basic MGNhNDE3Y2Y2OmYzYTkwNDg4" Basic credentials, generated as base_64_encode(client_id:client_secret)
{
  "method": "post",
  "url": "https://api-public-demo.menu.app/api/oauth/tokens",
  "headers": {
    "X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
    "Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
    "Api-Version": "<current-release-version>",
    "X-Role-ID": "",
    "X-Ordering-API": true
  },
  "body":{
    "grant_type": "client_credentials",
    "scope": "webhooks-management"
}
}

Response

{
    "status": "OK",
    "code": 200,
    "data": {
        "oauth_token": {
            "access_token": "d4c129d3f4560c2beaa3a1a3b15bb771a7038a4bbb680a3912c9ea284d07b291",
            "token_type": "bearer",
            "scope": "webhooks-management",
            "expires_in": 86399
        }
    }
}
Attribute Type Example Value Description
oauth_token.access_token string "f3a90488ffee32c3acb6fcd0ca417cf6" The client token. Send it on Authorization in the token exchange call below
oauth_token.expires_in int 86399 Token lifetime in seconds

Token Exchange

Now exchange the customer's token. POST /sts/users/sign-in registers the customer if needed, signs them in, and returns the PAR Ordering customer token.

Request

Attribute Type Example Value Description
Authorization string "Bearer 417cf6f3a90488ffee32c3acb6fcd0ca" The client token from the previous step
subject_token string "e32c3acb6fcd0ca417cf6f3a90488ffe" The customer's access_token from your identity provider
subject_token_type string "access_token" The type of the provided token
{
  "method": "post",
  "url": "https://api-public-demo.menu.app/api/sts/users/sign-in",
  "headers": {
    "X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
    "Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
    "Authorization": "Bearer e32c3acb6fcd0ca417cf6e32c3acb6fcd0ca417cf6e32c3acb6fcd0ca417cf6",
    "Api-Version": "<current-release-version>",
    "X-Ordering-API": true
  },
  "body":{
    "grant_type": "token_exchange",
    "subject_token": "test-1100-jane.doe@partech.com-Jane-Doe-+41767567126",
    "subject_token_type": "access_token"
  }
}

Response

{
    "status": "OK",
    "code": 200,
    "data": {
        "customer_account": {
            "id": "01e6d2c9-976b-4953-91e6-3dade887a4c7",
            "type_id": 1,
            "reference_type": "CustomerAccount",
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "jane.doe@partech.com",
            "phone_number": "+17126417675",
            "locale": "en",
            "state": 1,
            "demographics": [],
            "optin_status_email": 3,
            "optin_status_pn": 3,
            "has_pending_email_change": false,
            "has_pending_phone_number_change": false,
            "is_social": false,
            "social_login": null,
            "updated_at": "2023-09-20 07:38:47",
            "created_at": "2023-09-20 07:38:15",
            "confirmed": false
        },
        "token": {
            "value": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS1wdWJsaWMtcGxheWdyb3VuZC5tZW51LmFwcC9hcGkvc3RzL3VzZXJzL3NpZ24taW4iLCJpYXQiOjE2OTUxOTU1NDUsImV4cCI6MTY5NTE5OTE0NSwibmJmIjoxNjk1MTk1NTQ1LCJqdGkiOiJ1YUdxSDFKSlBzbUtWcEtjIiwic3ViIjoiNTA5MTUxNCIsInBydiI6ImNjMzI5MjFhMTU0ODBhMTE3ZDliYmM3MmMwZTEyNTZhNjg1MjQ1OGIiLCJhcHBsaWNhdGlvbl9pZCI6MjAxNSwic2Vzc2lvbl9pZCI6MzIyMDQsIl9vYXBpX3N0c190b2tlbiI6MX0.xWaQxNP1vAw-VYNS-VwmmXmYM_Ggw6dCW72L6leC89w",
            "ttl": 60,
            "issued_token_type": "access_token",
            "token_type": "Bearer"
        }
    }
}
Attribute Type Example Value Description
customer_account object The customer's account, populated from the profile your /customer-info endpoint returned
customer_account.id string "90488ffee32c3acb6fcd0ca417cf6f3a" Customer account UUID
customer_account.first_name string "Jane" Customer first name
customer_account.last_name string "Doe" Customer last name
customer_account.email string "jane.doe@partech.com" Customer email address
customer_account.phone_number string "17126417675" Customer phone number
token.value string "b6fcd0ca417cf6f3a90488ffee32c3ac" The PAR Ordering customer token

Send token.value as a Bearer token on the Authorization header of every customer-scoped call from here on.

SSO with Punchh Integration

On a brand integrated with Punchh the response also carries dlc_access_token, the Punchh token for the Dlc-Authorization header. See Authenticating to Punchh for when to send it and which token it carries.

Response

{
    "status": "OK",
    "code": 200,
    "data": {
        "customer_account": {
            "id": "01e6d2c9-976b-4953-91e6-3dade887a4c7",
            "type_id": 1,
            "reference_type": "CustomerAccount",
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "jane.doe@partech.com",
            "phone_number": "+17126417675",
            "locale": "en",
            "state": 1,
            "demographics": [],
            "optin_status_email": 3,
            "optin_status_pn": 3,
            "has_pending_email_change": false,
            "has_pending_phone_number_change": false,
            "is_social": false,
            "social_login": null,
            "updated_at": "2023-09-20 07:38:47",
            "created_at": "2023-09-20 07:38:15",
            "confirmed": false
        },
        "token": {
            "value": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS1wdWJsaWMtcGxheWdyb3VuZC5tZW51LmFwcC9hcGkvc3RzL3VzZXJzL3NpZ24taW4iLCJpYXQiOjE2OTUxOTU1NDUsImV4cCI6MTY5NTE5OTE0NSwibmJmIjoxNjk1MTk1NTQ1LCJqdGkiOiJ1YUdxSDFKSlBzbUtWcEtjIiwic3ViIjoiNTA5MTUxNCIsInBydiI6ImNjMzI5MjFhMTU0ODBhMTE3ZDliYmM3MmMwZTEyNTZhNjg1MjQ1OGIiLCJhcHBsaWNhdGlvbl9pZCI6MjAxNSwic2Vzc2lvbl9pZCI6MzIyMDQsIl9vYXBpX3N0c190b2tlbiI6MX0.xWaQxNP1vAw-VYNS-VwmmXmYM_Ggw6dCW72L6leC89w",
            "ttl": 60,
            "issued_token_type": "access_token",
            "token_type": "Bearer"
        },
        "dlc_access_token": {
            "value": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImphbmUuZG9lQHBhcnRlY2guY29tIiwiaWQiOjMwNjIyMzcyNiwiZXhwIjoxNjkwODE0NDUzfQ.ZqL4WcTKcMjdMycSBG6E32Ci98Rv_VUaqaXuzS4u-7w",
            "ttl": 60,
            "issued_token_type": "access_token",
            "token_type": "Bearer"
        }
    }
}
Attribute Type Example Value Description
dlc_access_token.value string "eyJlbWFpbCI6ImphbmUuZG9lQHBhcnRlY2guY29tIiwiaWQiOjMwNjIyMzcyNiwiZXhwIjoxNjkwODE0NDUzfQ" The Punchh token, sent as a Bearer token on Dlc-Authorization

Token Refresh Flow

Tokens issued by the exchange cannot be refreshed with Refresh Customer Token. When a call returns 401, run the exchange again. Because each exchange re-reads the customer's profile from your /customer-info endpoint, a changed name, email or phone number is picked up at the same time — there is nothing extra to call to keep the two systems in sync.

SSO-Token-Refresh.jpg

The sequence is: call a protected resource with the customer token, get 401, repeat the Register/Login to PAR Ordering steps to get a fresh token, retry the call.

Signing in to an existing white-label account

A brand can run a PAR white-label app and your custom app side by side. Customers keep one account, so saved cards, addresses and discounts are the same in both.

To make that work, the exchange looks the customer up in two steps: first by the customer_account_id your identity provider returns, then — if nothing matches — by email address.

SSO-Login-to-Whitelabel-Account.jpg

A match on customer_account_id signs the customer in directly. A match on email attaches your identifier to the existing account and signs them in to it, so a customer who registered in the white-label app lands in the same account when they arrive through your identity provider.