Authentication
The In-Store POS API requires specific permissions, encryption, and integrator tokens.
Permissions
There are several permissions that have to be granted to the token to use the In-Store POS API requests. Confirm the required permissions with your Genius account manager. Permissions include:
Permission | Required for These Requests |
|---|---|
Xenial.POS.API | Any In-Store POS API request except GET /info |
POSAPI.Order.Delete | |
POSAPI.Order.Committed.Delete | DELETE /order/{_id}, if an order, which is requested to be deleted, has been already committed to the point of sale (POS) |
POSAPI.Order.Paid.Delete | DELETE /order/{_id}, if an order, which is requested to be deleted, has order.payment_status = |
POSAPI.Order.Other_origin.Delete | DELETE /order/{_id}, if an order, which is requested to be deleted, has origin other than |
POSAPI.Order.View | |
POSAPI.Payment.Delete | |
POSAPI.Payment.Committed.Delete | DELETE /order/{_id}/payment, if the payment exists in the POS order version, which means that the payment is already committed or created on the POS |
Encryption
In-Store POS API requires both the point of sale (POS) and the client application encrypt and decrypt messages through Advanced Encryption Standard (AES) 256 cryptographic functions using symmetric keys. All requests and responses are encrypted, with the exception of GET /info and errors in the responses.
The sender of each request (either the POS or the client application) should generate a random initialization vector encoded as a base64 string and include it with the headers of the request. All encrypted requests have the following required header fields:
sec-iv: <initialization_vector> sec-fingerprint: <secret_key_identifier>
To obtain encryption keys:
Generate a token from Genius Portal using POST {{portal_url}}/integrator/token as listed in Getting Started.
Retrieve the site's encryption keys using GET {{portal_url}}/v1/company/{{company_id}}/sites/{{site_id}}?$select=type,name,security.
Use the encryption key from the GET response that is valid for the current date and time by locating the
valid_afterandvalid_untilvalues as shown in the example below.
The response includes the security object, which includes the encryption keys:
{
"security": {
"XPI": {
"encryption": true,
"keys": [
{
"fingerprint": "480bffa82df450cdb28e83abeba4c3fa",
"value": "3602f899b57fbfdae70494a1672de8d6",
"valid_after": "2026-09-22T00:00:00.000Z",
"valid_until": "2026-10-13T00:00:00.000Z"
},
{
"fingerprint": "ba1e0f56b1c830bf10d95426a9d4c2c6",
"value": "46068817e88cf1a35e7b29aa08137cde",
"valid_after": "2026-10-06T00:00:00.000Z",
"valid_until": "2026-10-27T00:00:00.000Z"
}
]
}
}
}Obtain an Integrator Token
The In-Store POS API service provides the ability to obtain an integrator token. Use the encryption keys to generate a token through In-Store POS API using POST http://{{ip-address}}:{{port}}/integrator/token request. For additional information regarding request format, see URLs for In-Store POS API Requests.
Note
The value of generating a token through the In-Store POS API is that the point of sale (POS) makes a call to the Portal API to generate a token and then caches that token. If the Portal is unavailable for future requests, the POS continues to honor the token until it receives a response that it has expired.
POST /integrator/token
Summary
Use the POST /integrator/token endpoint to generate bearer tokens for integrators.
Request Parameters
In | Field Name | Type | Required | Description |
|---|---|---|---|---|
header |
| string | Yes | The initialization vector |
header |
| string | Yes | The secret key ID |
body |
| Yes | The key identifier and secret key used to obtain an integrator token |
Responses
Code | Description |
|---|---|
200 | Success Message: Token returned in response body. |
401 | Error Message: Invalid credentials provided. |
IntegratorCredentials Object
Field Name | Type | Required | Description |
|---|---|---|---|
| string | Yes | The key identifier for the integrator |
| string | Yes | The secret key for the integrator |