Skip to content
DEV preview — API version 1.0.0 — not the public production site — Development API: dev-api.theprioryshop.co.uk
EPOS Developer API

API Keys

Every request to /v1/* authenticates with a static Integration API key, sent as a Bearer token:

Authorization: Bearer epos_dev_sk_example_not_real

This is not a JWT and not OAuth2 - it’s a long-lived, static secret string, similar in spirit to keys used by many server-to-server APIs. Staff/Back Office login sessions are never valid for /v1 - there’s no overlap between how a person logs into Back Office and how an integration authenticates here.

What a key belongs to

Section titled “What a key belongs to”

Every key belongs to exactly one IntegrationClient - a record representing one integration (e.g. “Acme Loyalty App - Production”), created by an EPOS owner in Back Office Developer Tools. An IntegrationClient has:

  • a tenant - your requests only ever see that tenant’s data, never anyone else’s; you cannot pass a tenant ID yourself, it’s derived entirely from the key,
  • a set of granted scopes - your requests can only reach routes whose required scope you hold,
  • an optional store restriction - if set, your requests can only see those specific stores; if unset, you see every store in the tenant,
  • a status (active/disabled/revoked) - a disabled or revoked client’s keys stop working immediately.

Key format

Section titled “Key format”
epos_<environment>_sk_<public-prefix>_<secret>

<environment> is dev or live, matching the environment the key was issued for - a Development key is rejected by the Production API and vice versa. The <public-prefix> is a stable, non-secret identifier used to look up which credential a request is using (visible in EPOS’s own logs/audit trail so an owner can tell which key did what, without ever storing or logging the full secret). <secret> is the actual cryptographically random secret portion.

The full secret is shown once

Section titled “The full secret is shown once”

When a key is created or rotated, the full secret is displayed exactly once, at that moment. EPOS stores integration credentials securely and does not allow retrieval of a previously issued secret - if you lose it, the only recovery path is rotating to a new one. Plan your deployment process around capturing the secret immediately into wherever you store secrets (environment variable, secret manager) - never into a place you’d have to come back and re-read later.

What’s next

Section titled “What’s next”