Identity API

The Identity API provides OAuth 2.0 authentication for the ShopHero CommerceCore platform. Use this API to obtain JWT tokens for accessing platform services like EngageHQ, DataCore, and others.

Overview

The Identity service implements industry-standard OAuth 2.0 authentication using the Client Credentials grant type. This is the same pattern used by services like Stripe, Shopify, and AWS.

Authentication Flow

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Your App      │     │  Identity API   │     │  EngageHQ API   │
│   (Backend)     │     │                 │     │                 │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │  POST /oauth/token    │                       │
         │  (client credentials) │                       │
         │──────────────────────>│                       │
         │                       │                       │
         │   JWT Access Token    │                       │
         │<──────────────────────│                       │
         │                       │                       │
         │                       │   GET /public/v1/...  │
         │                       │   (Bearer token)      │
         │───────────────────────┼──────────────────────>│
         │                       │                       │
         │                       │      JSON Response    │
         │<──────────────────────┼───────────────────────│
         │                       │                       │

Base URLs

Environment	URL
Staging	https://identity-staging.retailsuccessplatform.com
Production	https://identity.retailsuccessplatform.com

Quick Start

1. Get Your Credentials

Contact your ShopHero administrator to create a service account. You'll receive:

• Client ID - Your application identifier
• Client Secret - Your secret key (store securely!)

Important

Client secrets are only shown once when created. Store them securely in your backend environment variables. Never expose them in frontend code.

2. Exchange Credentials for Token

curl -X POST https://identity.retailsuccessplatform.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=engagehq:content.view engagehq:circulars.view"

3. Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 86400
}

4. Use the Token

Include the token in API requests:

curl https://api.engagehq.retailsuccessplatform.com/public/v1/content \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."

Token Lifecycle

Token Type	Expiration	Renewal
Access Token	24 hours	Request new token via /oauth/token
Refresh Token	30 days	Use refresh endpoint (user auth only)

Available Scopes

Scopes control what resources your token can access. Scopes follow the pattern service:resource.action:

Scope	Description
engagehq:*	Full access to EngageHQ API
engagehq:content.view	View CMS content items
engagehq:content.create	Create new content items
engagehq:circulars.view	View weekly circulars
engagehq:offers.view	View promotional offers
datacore:*	Full access to DataCore API
datacore:products.view	View products
datacore:categories.view	View category hierarchy
kitchenclick:*	Full access to KitchenClick ecommerce API
kitchenclick:menus.read	Check item availability
kitchenclick:orders.calculate	Calculate order totals
kitchenclick:orders.create	Create guest orders
kitchenclick:payments.read	Check payment status
kitchenclick:payments.create	Create payment requests
kitchenclick:kiosks.bootstrap	Initialize kiosks
kitchenclick:kiosks.heartbeat	Send kiosk heartbeats

Security Best Practices

1. Never expose credentials in frontend code - Always make token requests from your backend server
2. Use environment variables - Store client_id and client_secret in environment variables
3. Implement token caching - Cache tokens until near expiration to reduce API calls
4. Use HTTPS only - Never transmit credentials over unencrypted connections
5. Rotate credentials regularly - Request credential rotation every 90 days

Next Steps

• Getting Started Guide - Detailed setup instructions
• Service Accounts - Managing service accounts
• OAuth Token Reference - Complete endpoint documentation
• JWT Structure - Understanding token contents

---

Changelog

Date	Change
2026-03-14	Accuracy fixes and added missing content.
2026-02-27	Documentation corrections.
2026-01-15	Initial publication.