API Keys

Every authenticated Streaming API call must identify the Company with three headers: X-Api-Key, X-Api-Secret, and X-Api-Version. This page explains how those credentials are managed and how the integration should use them.

Low-level HTTP rules (case-sensitive header names, errors, rate limits): HTTP API.

What the credentials are

Header	Role
X-Api-Key	Public identifier of the API key for the Company.
X-Api-Secret	Secret paired with the key. Treat it like a password.
X-Api-Version	API version. Current public integrations use 1.

X-Api-Key: <api-key>
X-Api-Secret: <api-secret>
X-Api-Version: 1

Header names are case-sensitive. A wrong or missing credential typically returns 403 with a Forbidden-style body.

Where to manage keys (Owner App)

In the Owner App, Streaming API keys live under Data Collection → API Keys (Customer Data Platform / data collection area).

Operators can:

Action	Notes
Create new API Key	Provide a Description and set Enabled. The platform generates the key value and secret.
View	Inspect the key (X-api-key) and secret (X-api-secret) values for the selected record.
Edit	Update description or enabled status. System keys cannot be edited.
Enable / disable	Disable a key to revoke access without deleting the record.

caution

Copy the secret when it is available and store it in your secret manager. Do not commit keys to git, Postman shared workspaces without access control, or ticket comments.

Who creates the first key

Projects usually follow one of these paths:

Path	When
Loyal Guru provisions keys	Common during onboarding / sandbox setup. The LG team shares key and secret out of band.
Retailer creates keys in Owner App	When the Company already has Owner App access and Data Collection permissions.

Either way, use separate keys for sandbox and production Companies. Never reuse production secrets in a test environment.

Integration checklist for credentials

• One key per environment (sandbox vs production) and preferably per consuming system (POS middleware vs e-commerce vs batch jobs).
• Rotate keys when an integrator leaves the project or a secret may have leaked.
• Disable unused keys instead of leaving them enabled indefinitely.
• Confirm X-Api-Version: 1 on every authenticated request.
• After creating a key, validate with a low-risk call such as GET /check or a sandbox POST /carts/simulate.

Related setup

Topic	Guide
Product and store master sync	Company Data
Customer identity	Customer Data
First cart call	Quickstart
Full launch checklist	Integration Checklist
Product configuration context	Data Collection

Troubleshooting

Symptom	What to check
403 Forbidden	Key/secret/version headers; enabled flag; correct Company/environment base URL.
Works in sandbox, fails in production	Different Company credentials; secret not updated after cutover.
Key visible but secret unknown	Create a new key, update the integration, then disable the old key.
System key cannot be edited	Expected for platform-managed keys — create a project-specific key instead.