Authentication

Every request carries your token in the X-KATALYST-AUTH-TOKEN header:

GET /v1/integration/loyalty/card/?number=WD-100234 HTTP/1.1
Host: dev-api.katalystos.com
X-KATALYST-AUTH-TOKEN: <your token>

The API also accepts Authorization: Bearer <your token>, but use X-KATALYST-AUTH-TOKEN: it is what the examples and the API reference use.

Tokens

• One token per integration and restaurant. KatalystOS issues them; see Getting started.
• Scoped by permission. A token only reaches the endpoints its permissions allow, so a loyalty token cannot read reports and the other way round.
• Bound to a restaurant. The loyalty endpoints default to the token’s restaurant. Pass restaurant_id only when KatalystOS has set your integration up for several restaurants.
• Long-lived. Tokens do not expire on a schedule. Ask KatalystOS to revoke and reissue one if it leaks or a person who had it leaves.

Caution

Treat the token like a password. Call the API from your server only; never embed the token in a web page or mobile app.

When a token is rejected

These are the only responses that use a non-200 status code.

Missing or unknown token: HTTP 401

{ "success": false, "error": "Access Denied" }

Token lacks the endpoint’s permission: HTTP 403

{
  "success": false,
  "errors": { "system": ["You haven't permission to access this feature"] },
  "error_code": 403
}

The report endpoints are scoped to a restaurant in the URL. Calling one for a restaurant your token does not belong to returns HTTP 200 with success: false and error_code: 403.

Fingerprint

Every response includes a fingerprint, a short id of the token that made the call. Quote it when you contact KatalystOS about a request; it identifies your token without exposing it.