API Keys

API keys provide a simple, credential-based authentication method for POS terminals, ETL pipelines, and hardware integrations where running an OAuth flow is impractical.

Format

API keys follow the format rsa_live_{40-hex}. Example:

rsa_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Usage

Pass the key in the X-Api-Key request header:

curl "http://localhost:5003/pos/api/v1/members/lookup?phone=5551234567" \
  -H "X-Api-Key: rsa_live_your_key_here"

API keys can authenticate against the POS API and are also accepted by the Admin API for ETL integrations. They do not work with the Platform API or Shopper API.

Creating an API Key

API keys are created as OAuth clients of type PosApp or IntegrationApp via the Admin API:

POST/admin/api/v1/clients

curl -X POST http://localhost:5002/admin/api/v1/clients \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appType": "PosApp",
    "name": "Store #001 POS Terminal",
    "scopes": ["pos.read", "pos.write"]
  }'

Response (secret shown once):

{
  "clientId": "pos_store_001",
  "apiKey": "rsa_live_a1b2c3d4...",
  "scopes": ["pos.read", "pos.write"]
}

The apiKey is shown exactly once. Store it securely in your POS terminal's configuration. If lost, rotate via POST /admin/api/v1/clients/{id}/rotate-secret.

Rate Limits

POS API keys have a 500 requests/minute fixed window rate limit. Exceeding this returns 429 Too Many Requests. Implement exponential backoff with jitter in your POS client.

Security Best Practices

Store keys in encrypted configuration (environment variables, HSM, or secure vault)
Use one API key per POS terminal for independent rotation
Rotate keys on a schedule or immediately if a terminal is decommissioned
Only grant the scopes your terminal needs (pos.read + pos.write for most cases)