Skip to main content

Portal

Secret Key Collection

The concept of using 2 security keys (previous and current) always provides clients with the ability to decrypt the message. This is especially important since the Portal uses a centralized Security Key storage and is unable to guarantee that all clients are able to updated their security key at the same time.

Each Secret Key has a unique identifier (fingerprint) used in headers. This fingerprint identifies the exact key used for the encryption process. 

Because an overlapping time frame exists between the 2 keys (previous and current), the old key remains valid for a period of time, even after the generation of a new key. This concept was purposefully applied so that clients are still able to understand (encrypt/decrypt) each other seamlessly—even with different secret keys—for a period of time.

Retrieving Secret Keys from the Portal

To obtain a Secret Key from the collection (maximum size of 2), it is necessary to retrieve a Site Object. 

URL to Obtain a Site Object

Warning

An authorization header is required with this request.

https://<portal_url>/sites/<site_id>

  • portal_url - the portal URL acquired from the SSR

  • site_id - current unique identifier for the site

Site Object Security Field

The Site Object contains the Security field.

The Security field consists of dedicated services—such as Enterprise Kitchen, etc.—) and the security model inside of each. 

The Enterprise Kitchen service is represented with:

  • encryption - boolean type, regulates if application should use encrypted communication

  • keys - [Optional] collection of keys (pass phrases)

The key model has:

  • fingerprint - a unique identifier for key, an encrypted UUID with MD5 or similar algorithm

  • value - the secret key in string format

  • valid_after - UTC timestamp in ISO-8601 format that identifies the date/time validity of the current key

  • valid_until - UTC timestamp in ISO-8601 format that identifies the date/time expiration of the current key

Note

[Optional] fields presented only when encryption field is true.

Example

The site object contains the security field:

{
  ...
  active: true,
  all_active_and_inactive_subscriptions: ['XKS'],
  alternate_languages: [],
  automatic_updates: false,
  business_type: "QSR",
  edm_sync: true,
  email: "",
  environment: "Production",
  hierarchies: [],
  identifiers: {federal_tax: '', state_province_tax: ''},
  is_active: true,
  is_demo: false,
  metadata: [],
  name: "Restaurant 1",
  phone_number: "111111111",
  phone_settings: {code: '1', country: 'us', number: '111111111'},
  preferred_language: "en-US",
  preferred_language_name: "English - United States",
  preferred_language_native_name: "English (US)",
  roles: [],
  security: { 
      XKM: {
        "encryption": true,
        "keys": [
          {
            "fingerprint": "b6e4b70983144e192bd7eea24c698f54",
            "value": "secret",
            "valid_after": "2024-06-11T00:00:000Z",
            "valid_until": "2024-07-11T00:00:000Z"
          },
          {
            "fingerprint": "8ad8c9b0faedd4799805510a91578849",
            "value": "secret",
            "valid_after": "2024-07-04T00:00:000Z",
            "valid_until": "2024-08-11T00:00:000Z"
          }
        ]
      }
  store_number: "1",
  subscriptions: ['XKS'],
  support_phone_number: "",
  support_phone_option: "Use Company Settings",
  support_phone_settings: {code: '', country: '', number: ''},
  tasks: [],
  timezone: "US/Pacific",
  type: "Production",
  website: "",
  ...
}

Secret Key Rotation Interval

To further enhance security, the Portal updates the Secret Keys collection with a defined validity interval. 

  • Encryption and decryption processes involve the same Secret Key

  • Enterprise Kitchen and POS share a very close Secret Key update time frame interval to that of the Portal

  • Enterprise Kitchen has a period of time when both secret keys (previous and current) are valid to decrypt the message—minimizing risk when POS or Enterprise Kitchen does not simultaneously update the Secret Key

  • The Secret Key update process for Enterprise Kitchen, POS and the Portal to remain consistent—TBD

See also: