Offline verification

Check a batch’s serials in your own systems, without internet, using the batch’s verification key.

Batches set to offline, or online and offline can be checked by your own systems with no connection to Satyakod. Two ways, which you can combine:

Way	Confirms	Needs
Serial list	The serial is one you issued, and whether it is revoked	The batch’s Serial list (CSV)
Verification key	The serial’s signature is genuine and it is inside the batch	The batch’s key and about 20 lines of code

The key is better for large batches and for codes you didn’t download in advance; the list also tells you about revocations made after the key was loaded.

Get the verification key

1. Open the batch

   Batches, then the batch. The key exists once the batch is signed.

2. Download the key

   Under Offline checking, admins download Verification key · JSON. Each download is recorded in the audit log.

3. Load it into your system

   Store it where your system keeps other secrets, never in an app or device that leaves your control.

An offline batch: Offline checking and its verification key

B-1045-verification-key.json

{
  "batch": "B-1045",
  "batchSeq": 1045,
  "quantity": 80000,
  "workspaceId": "ws_example0000000001",
  "keyId": "example-2026-01",
  "algorithm": "HMAC-SHA256, first 4 bytes",
  "key": "Xd0K9tB+7Ni/P3YcbfecPYU8TgLzLdpXIT19ic9+SKo="
}

Anyone who has a batch’s key can make serials that pass offline checks for that batch. It can’t make serials for any other batch or brand, and Satyakod’s own checks still catch copies (clone detection) once scans are uploaded. Keep keys in your factory and warehouse systems only: never ship one in a consumer app, a web page or a scanner you lend out.

Field scanners’ phones

Your field scanners can check offline batches in the Satyakod app without handling keys:

1. Enrol the phone

   Settings → Offline devices: name the phone, choose the field scanner, then Enrol device. You get a one-time code, valid for 30 minutes.

2. Turn it on in the app

   Signed in as that field scanner, Account → Offline checking, then type the code.

The phone keeps the keys of your offline batches (at the printer or printed) in its secure storage, for that person only, for 7 days; they renew whenever the screen is opened online. Results checked offline say so, and the scans are verified and recorded once the phone is back online. Revoke a phone under Offline devices and it loses its keys at its next sync; signing out of the app deletes them at once.

Check a serial

A serial is genuine for the batch when its tag equals the first 4 bytes of HMAC-SHA256(key, message), where the message is workspaceId|keyId| followed by the serial’s 6-byte batch sequence and index. See Serial numbers for the format.

Python

import base64
import hashlib
import hmac

ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
DECODE = {c: i for i, c in enumerate(ALPHABET)} | {"O": 0, "I": 1, "L": 1}


def check_serial(serial: str, key: dict) -> bool:
    """True when `serial` is one of this batch's serials. `key` is the verification key JSON."""
    text = serial.strip().upper().replace("-", "").replace(" ", "")
    if len(text) != 16 or any(c not in DECODE for c in text):
        return False
    value = 0
    for c in text:
        value = (value << 5) | DECODE[c]
    tag = (value & 0xFFFFFFFF).to_bytes(4, "big")
    payload = value >> 32
    batch_seq, index = payload >> 24, payload & 0xFFFFFF
    if batch_seq != key["batchSeq"] or index >= key["quantity"]:
        return False
    message = f"{key['workspaceId']}|{key['keyId']}|".encode() + payload.to_bytes(6, "big")
    expected = hmac.new(base64.b64decode(key["key"]), message, hashlib.sha256).digest()[:4]
    return hmac.compare_digest(expected, tag)

Test your implementation

With the example key above:

Serial	Expected
0021A00002YSXBWW	genuine (item 0)
0021-A051-2PXK-20J9	genuine (item 41,237; hyphens are ignored)
0021A0512PXK20J0	not genuine (last character changed)

The example key is made up for these docs. It belongs to no workspace, and its serials won’t pass Satyakod’s online checks.

What an offline check can’t tell you

• Copies. A genuine serial printed twice passes offline. Satyakod’s clone check compares scans across places and times; upload your offline scans to get it.
• Revocations after you loaded the key. Download the Serial list again, or check online when you can, for batches you have revoked codes from.

Upload scans made offline

When the device or plant is back online, send its scans to POST /v1/verify/offline, up to 500 at a time. Satyakod checks each as of when it was scanned and adds it to your scan history, alerts and reports.