Authorization

Basic authentication, integrator headers and rate limits.

Basic authentication

Every request carries Authorization: Basic base64(apiKey:apiSecret). The apiKey is public and may be logged; the apiSecret is secret and is shown only once, when it is generated. The Token field in the partner console is this base64(apiKey:apiSecret) value itself and can be put in the header as is.

Building the header

printf '%s:%s' "$API_KEY" "$API_SECRET" | base64

The key prefix names its environment: ck_live_ for production, ck_test_ for the test environment. A key sent to the wrong environment receives 401 environment_mismatch; the X-Api-Environment header on every response shows which environment you are talking to.

Each key pair is bound to a single business. The key determines the business and the vertical (restaurant or store); no business identifier is sent in the request. The merchantId in responses is the identifier of the business. This identifier is not the merchant number of a bank or payment institution; it is your business identifier on the platform.

If the apiSecret leaks, rotate it from the partner console; the old secret is invalidated immediately. A leaked secret leaves the business's catalogue and orders open to a third party.

Integrator headers

Alan	Tip	Açıklama
`X-Integrator`zorunlu	string	The name of the company that develops the point-of-sale software. 1–30 characters; letters, digits and spaces without Turkish characters (example: `Ornek POS`). For in-house software, use your company name. Missing or invalid values return `403 integrator_header_required`.
`X-Operator`	string	Optional. The identifier of the user at the point of sale: at most 64 characters; letters, digits and `. _ : -`. Do not send an e-mail address. If absent, `otomatik` is recorded. Invalid values return `400 invalid_operator`.
`X-Request-Id`	string	Optional. If you send it, leading and trailing spaces are removed, the value is cut to 64 characters and returned in the response. If you do not send it, one is generated.

The X-Integrator and X-Operator values appear in the business's order history and audit trail: which software and which point-of-sale user performed an action is read from these two fields.

Rate limits

50 requests per 10 seconds per service group and key. Counting is per group, not per endpoint. Order and store endpoints are in a different group from the catalogue; a large catalogue upload does not block order acceptance. For the endpoints in each group and the other limits, see Service limits.

The remaining budget is reported on every response that reaches authentication (including 304 and error responses) in the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. On overflow the response is 429 with Retry-After.

Authorization errors

Alan	Tip	Açıklama
`401`	unauthorized	The key or password is invalid, the key is disabled or the business link is broken.
`401`	environment_mismatch	The key belongs to the other environment (`ck_test_` in production or `ck_live_` in the test environment); the message names the correct address.
`403`	integrator_header_required	The `X-Integrator` header is missing or invalid.
`400`	invalid_operator	The `X-Operator` value is invalid.
`404`	not_found	The record does not exist or does not belong to this business. The response is the same in both cases.
`404`	not_available_for_vertical	The endpoint does not exist for this business's vertical. The message names the vertical where it exists.
`429`	too_many_requests	A rate limit was exceeded; `reason` names which one, wait for `Retry-After` seconds.

A record of another business returns 404, not 403: a 403 would confirm that the record exists. See Error codes for the full list.