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 ​

API keys are provisioned through the iorder admin UI. Contact your iorder administrator to create a service device and obtain the corresponding API key. The admin UI generates service device sessions and provides the session's API key for use in integrations.

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 API key maps to a server-side session. The session:

  • Has a configurable timeout period.
  • Is tied to a specific location and device.
  • Is refreshed on each API call made with the key.
  • May expire after prolonged inactivity. If a session expires, the API returns a 401 error.
  • May be deleted explicitly by the server on session timeout events.

Keep the session alive by polling at regular intervals. The SSE notification stream also keeps the session active.

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. This throttling mechanism makes brute-force key guessing impractical. 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 ​

The 401 throttling (500-1499ms random delay) is a soft rate limit. To avoid compounding latency:

  • Do not retry immediately on 401. Wait at least 2 seconds before retrying.
  • Implement exponential backoff: 2s, 4s, 8s, 16s, capped at 60s.
  • If you receive repeated 401 responses, the API key is likely invalid or expired. Generate a new one through the admin UI.
  • Monitor your 401 rate. A high rate indicates a configuration issue or expired key.

Next Steps ​