Authentication & Authorization

Access to the NX Restaurant (NXR) API is restricted to approved integrators.

Integrators are issued a unique NXR Integrator API Key and NXR Integrator API Secret upon approval.

These credentials are required for all requests to the API.

🔑 Authentication Overview

The NX API supports two authentication mechanisms depending on the integration type:

🧠 Basic Authentication

Integrators performing server-to-server requests must authenticate using HTTP Basic Authentication.

Format

Each request must include the Authorization header encoded in Base64:

Authorization: Basic <Base64Encoded(API_KEY:API_SECRET)>

Example

Header

Authorization: Basic MjRjOWEzMTAtNGI1NC00MmMyLWJlODgtNjRlN2YzN2M0NzQxOnlvdXJfYXBpX3NlY3JldF9rZXk=

🔒 HMAC Authentication

Integrators performing client-to-server requests (e.g., POS clients, mobile apps, web apps) must use NX’s HMAC Authentication scheme.

This ensures each request is securely signed and tamper-proof.

HMAC Construction

To create a valid HMAC signature:

1. API_KEY:HTTP_METHOD:REQUEST_PATH:TIMESTAMP:NONCE

Notes:
The URL must exclude protocol (https://), query parameters, and any port overrides.The TIMESTAMP must be the current Unix time in milliseconds.
The NONCE must be a unique, random value (we recommend a UUIDv4 or GUID).

Example Components

Concatenated String

24c9a310-4b54-42c2-be88-64e7f37c4741:get:prod.api.nxapp.net/api/v1/sales/orders:1728659738:8d46d845-40c3-49de-927c-f8cbd9006fbf

HMAC Signature Generation

Using the concatenated string, generate a Base64-encoded HMAC-SHA256 hash using your API Secret as the key.

The resulting hash is your signature.

Header Format

Include both the API Key and signature in your request headers:

Authorization: HMAC <API_KEY>:<SIGNATURE>
x-nx-timestamp: <TIMESTAMP>
x-nx-nonce: <NONCE>

💻 Implementation Examples

Below are example implementations in several popular programming languages.

JavaScript

function generateHash(message, secret) {
  const crypto = require('crypto');
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(message);
  return hmac.digest('base64');
}

Kotlin

import java.util.Base64
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
fun digest(message: String, key: String, alg: String = "HmacSHA256"): String {
    val signingKey = SecretKeySpec(key.toByteArray(), alg)
    val mac = Mac.getInstance(alg)
    mac.init(signingKey)
    val bytes = mac.doFinal(message.toByteArray())
    return Base64.getEncoder().encodeToString(bytes)
}

Swift

import Foundation
import CryptoKit
func digest(message: String, key: String, alg: String = "HmacSHA256") -> String? {
    guard let keyData = key.data(using: .utf8),
          let messageData = message.data(using: .utf8) else { return nil }
    let algorithm: CCHmacAlgorithm
    switch alg {
    case "HmacSHA256": algorithm = CCHmacAlgorithm(kCCHmacAlgSHA256)
    default: return nil
    }
    var hmac = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
    CCHmac(algorithm, keyData.bytes, keyData.count, messageData.bytes, messageData.count, &hmac)
    let hmacData = Data(hmac)
    return hmacData.base64EncodedString()
}
extension Data {
    var bytes: [UInt8] { [UInt8](self) }
}

C#

using System;
using System.Security.Cryptography;
using System.Text;
public class HashGenerator
{
    public static string GenerateHash(string message, string secret)
    {
        var keyBytes = Encoding.UTF8.GetBytes(secret);
        var messageBytes = Encoding.UTF8.GetBytes(message);
        using (var hmacsha256 = new HMACSHA256(keyBytes))
        {
            var hashBytes = hmacsha256.ComputeHash(messageBytes);
            return Convert.ToBase64String(hashBytes);
        }
    }
}

✅ Implementation Notes

• Each request must include unique timestamp and nonce values — replayed requests will be rejected.
• The timestamp must be within an acceptable clock drift window (typically ±5 minutes).
• The HMAC signature is case-sensitive and must be Base64-encoded.
• If any component of the signature string changes (method, URL, nonce, etc.), the signature must be recalculated.
• For debugging, the NX API may return an X-NX-Auth-Debug header containing information about failed signature validation.