Manuals

English

Deutsch

English

Deutsch

Appearance

Authentication ​

Every request to the iorder POS API requires authentication. The system uses API key authentication, where the key identifies a service device session.

API Key ​

The API key is a string that identifies a service device session. It must be included in every API request.

How to Obtain an API Key ​

Ask a restaurant administrator to follow API Keys and generate a key for the intended location. Use a service integration key, separate from a person's sign-in passkey. Store it privately and confirm the application base URL with the operator.

Sending the API Key ​

Pass the API key in one of two ways:

Header (recommended):

text
api_key: <your-api-key>

Query parameter:

text
?api_key=<your-api-key>

The server checks the api_key header first, then falls back to the query parameter if the header is absent.

Examples ​

Header-based authentication:

bash
curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/orders/location"

Query parameter authentication:

bash
curl -i "https://{host}/orders/location?api_key=abc123-def456-ghi789"

Session Lifecycle ​

The key identifies a server-side session associated with a device and location. Check authentication on every request, including reconnecting an event stream. An open SSE connection is not a guarantee that later requests will remain authorized.

If a request returns 401, check the configured host and key with the administrator. Do not generate a new key solely because the server restarted; first check whether the existing key still works.

Unauthorized Responses ​

There are two different 401 response shapes, depending on how the request fails:

AuthorizationInterceptor (missing or invalid API key) ​

When the API key is missing, empty, or does not match any active session, the AuthorizationInterceptor returns:

http
HTTP/1.1 401 Unauthorized
Content-Type: text/plain

{"error" : "Session not valid."}

The server deliberately adds a random delay between 500ms and 1499ms before responding. Expect this delay on every failed authentication attempt.

GlobalExceptionHandler (expired or unauthorized session) ​

When the API key is recognized but the session is no longer valid (e.g., expired or the session type is wrong), the UnAuthorizedException handler returns:

http
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"message": "Unauthorized", "uid": null}

This response also includes a random delay between 500ms and 1499ms.

Handling 401 Responses ​

Always check for both response shapes:

bash
curl -i -H "api_key: invalid-key" "https://{host}/orders/location"

Example output:

http
HTTP/1.1 401 Unauthorized
Content-Type: text/plain

{"error" : "Session not valid."}

Rate Limiting Guidance ​

Treat 401 as a credential/configuration problem rather than a transient server failure. Stop automatic processing and ask the operator to check the key, host, and location. Resume after correcting the configuration. A response body may be plain text or JSON, so branch on the HTTP status before parsing it.

Use bounded backoff for temporary network and server failures as described in Error Handling.

Next Steps ​