Authentication and API keys

Three kinds of authority

A vendor owner session is still a person’s session. It does not act as an integration key. The public reference does not define an OAuth client-credentials exchange or a long-lived owner automation token. Use the supported vendor portal for human sign-in.

Send credentials in headers

Authorization: Bearer <CREDENTIAL_FOR_THIS_OPERATION>
X-Terminal-Serial: <REGISTERED_TERMINAL_SERIAL>

The terminal header is required for POS calls and must identify a device in the same tenant as the key. Tenant IDs and serials are identifiers rather than passwords. Never pass a bearer credential in a URL or query parameter. Vendor routes explicitly reject query token authentication.

Use the smallest applicable scope

A key’s environment, revocation status and vendor approval are checked separately from its scope. Sandbox-only identity routes reject live keys. Confirm scope and reader binding before diagnosing a payload issue.

Credential lifecycle

Store a one-time sandbox key immediately in your server-side secret store. Key metadata can be displayed, but the raw key should not be logged, sent by email, committed or included in browser assets. Owner key listing and revocation are available for an approved vendor; live issuance and rotation return 503 until a supported secret-delivery channel is configured.

1. Obtain the credential through the agreed environment-specific channel.
2. Deploy it only to the backend or managed reader that needs it.
3. Record the display-safe prefix and environment for operational support.
4. Revoke credentials when a device is lost, staff access changes or a secret may have escaped.
5. Coordinate replacement before resuming traffic; do not assume a revoke creates a new key.