Skip to main content

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

DELETE /order/{_id}

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 = paid, partial, or awaiting_tip

POSAPI.Order.Other_origin.Delete

DELETE /order/{_id}, if an order, which is requested to be deleted, has origin other than pos-api

POSAPI.Order.View

GET order/{_id} and GET /order

POSAPI.Payment.Delete

DELETE /order/{_id}/payment

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:

  1. Generate a token from Genius Portal using POST {{portal_url}}/integrator/token as listed in Getting Started.

  2. Retrieve the site's encryption keys using GET {{portal_url}}/v1/company/{{company_id}}/sites/{{site_id}}?$select=type,name,security.

  3. Use the encryption key from the GET response that is valid for the current date and time by locating the valid_after and valid_until values 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

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

body

body

IntegratorCredentials Object

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

key_id

string

Yes

The key identifier for the integrator

secret_key

string

Yes

The secret key for the integrator