Client SDK

The client SDK lets your game client talk to a physically connected SentinelID USB dongle. It handles the HID framing protocol, reads the device’s signed DeviceCheckRequest, and hands it back to your code to forward to your game server.

The signed payload produced by the device must be forwarded to your game server, which then calls the Server SDK to verify it with the Sentinel Network API. Never send your API key to the game client.

Device VID / PID

All SDKs enumerate by the following USB descriptor. Note that these IDs are not exclusive to SentinelID hardware — the SDK matches on both VID and PID together.

Field	Value
Vendor ID	`0x239A`
Product ID	`0xCAFE`
Protocol	USB HID, 64-byte reports

Installation

npm install @sentinelid/client
# Requires node-hid (bundled as a dependency)

pip install sentinelid-client
# Requires hidapi (pip install hidapi)

<PackageReference Include="SentinelId.Client" Version="*" />
<!-- Requires HidSharp (bundled as a dependency) -->

implementation 'io.sentinel-id:sentinelid-client:1.0.0'
// Requires hid4java (bundled as a dependency)

# Requires: hidapi (system install)
#   Windows : vcpkg install hidapi
#   macOS   : brew install hidapi
#   Linux   : apt install libhidapi-dev
include(FetchContent)
FetchContent_Declare(
  sentinelid-client
  GIT_REPOSITORY https://github.com/C-Squared-Solutions-LLC/sentinelid-client-cpp.git
  GIT_TAG        v1.0.0
)
FetchContent_MakeAvailable(sentinelid-client)
target_link_libraries(your_target PRIVATE sentinelid-client)

Enumerate Devices

List all connected SentinelID dongles.

import { SentinelDevice } from "@sentinelid/client";

const devices = SentinelDevice.enumerate();
console.log(devices);
// [{ path: "/dev/hidraw0", vendorId: 0x239A, productId: 0xCAFE, ... }]

from sentinelid_client import SentinelDevice

devices = SentinelDevice.enumerate()
for d in devices:
    print(d.path, d.serial_number)

using SentinelId.Client;

var devices = SentinelDevice.Enumerate();
foreach (var d in devices)
    Console.WriteLine(d.Path);

import io.sentinelid.client.SentinelDevice;

var devices = SentinelDevice.enumerate();
devices.forEach(d -> System.out.println(d.getPath()));

#include <sentinelid/client/device.hpp>

auto devices = sentinelid::client::SentinelDevice::enumerate();
for (auto& d : devices)
    std::cout << d.path << "\n";

Open a Device and Request a Check

The typical flow is to open the first available device, send a check challenge, and receive a signed DeviceCheckRequest to forward to your server.

import { SentinelDevice } from "@sentinelid/client";

const device = SentinelDevice.openFirst();
try {
  const checkReq = device.requestCheck("pub_acme", "game_fps_01");
  // Forward checkReq to your game server
  const response = await fetch("/api/session/start", {
    method: "POST",
    body: JSON.stringify(checkReq),
  });
} finally {
  device.close();
}

from sentinelid_client import SentinelDevice

with SentinelDevice.open_first() as device:
    check_req = device.request_check("pub_acme", "game_fps_01")
    # Forward check_req to your game server
    response = requests.post("/api/session/start", json={
        "device_id":   check_req.device_id,
        "publisher_id": check_req.publisher_id,
        "game_id":     check_req.game_id,
        "alg":         check_req.alg,
        "payload_b64": check_req.payload_b64,
        "sig_b64":     check_req.sig_b64,
    })

using SentinelId.Client;

using var device = SentinelDevice.OpenFirst();
var checkReq = device.RequestCheck("pub_acme", "game_fps_01");
// Forward checkReq to your game server

import io.sentinelid.client.SentinelDevice;

try (var device = SentinelDevice.openFirst()) {
    var checkReq = device.requestCheck("pub_acme", "game_fps_01");
    // Forward checkReq to your game server
}

#include <sentinelid/client/device.hpp>

auto device = sentinelid::client::SentinelDevice::open_first();
auto check_req = device.request_check("pub_acme", "game_fps_01");
// Forward check_req to your game server
device.close();

Open a Specific Device

If multiple dongles are connected, select one by path.

const devices = SentinelDevice.enumerate();
const device  = SentinelDevice.open(devices[0]);

devices = SentinelDevice.enumerate()
device  = SentinelDevice.open(devices[0])

var devices = SentinelDevice.Enumerate();
var device  = SentinelDevice.Open(devices[0]);

var devices = SentinelDevice.enumerate();
var device  = SentinelDevice.open(devices.get(0));

auto devices = sentinelid::client::SentinelDevice::enumerate();
auto device  = sentinelid::client::SentinelDevice::open(devices[0]);

DeviceCheckRequest Fields

The object returned by requestCheck / request_check maps directly to the Device Check API body:

Field	Type	Description
`device_id`	string	Unique device identifier stored on the dongle
`publisher_id`	string	Echo of the `publisherId` argument
`game_id`	string	Echo of the `gameId` argument
`alg`	string	Signature algorithm — always `ES256`
`payload_b64`	string	Base64-encoded signed payload from the device
`sig_b64`	string	Base64-encoded ES256 signature

HID Protocol

The SDK handles the low-level framing automatically. Each HID report is 64 bytes.

Write (host → device)

Output reports use the following header layout:

Byte	Field	Value
0	Report ID	`0x00`
1	CMD	`0x03` (SIGN_PAYLOAD)
2	FLAGS	`START=0x01`, `END=0x02`
3	SEQ	Packet sequence number (0-based)
4–63	DATA	Challenge JSON chunk

The challenge JSON {"publisher_id":"…","game_id":"…"} is split into 60-byte chunks and spread across one or more reports. The START flag is set on the first report; the END flag is set on the last.

Read (device → host)

Input reports have no leading report ID byte:

Byte	Field	Value
0	CMD	Echo of the command
1	FLAGS	`START=0x01`, `END=0x02`, `ERROR=0x04`
2	SEQ	Packet sequence number
3–63	DATA	Response JSON chunk

Reports are read and concatenated until FLAG_END is set. If FLAG_ERROR is set, byte 3 contains an error code:

Code	Name	Description
`0x01`	`BUSY`	Device is processing a previous request
`0x10`	`BAD_STATE`	Unexpected command in current state
`0x11`	`PAYLOAD_TOO_LARGE`	Challenge exceeded device buffer
`0x30`	`RATE_LIMIT`	Too many requests — back off and retry
`0x40`	`ATECC_FAIL`	Secure element signing failure
`0xFF`	`UNKNOWN_CMD`	Unrecognized command byte
`0xE0`	`PROVISION_DENIED`	Device not provisioned for this publisher

Reads time out after 5 seconds; a TimeoutError / RuntimeException is thrown if no response is received.

Sandbox Testing

During development you can use the sentinelid-sim package to generate valid signed payloads without physical hardware. The simulator persists its identity (device ID + EC key pair) on first run, so the same device ID is reused across test sessions.

pip install sentinelid-sim

# Register the simulated device with your sandbox environment (once)
sentinelid-sim register --api-key sni_sandbox_... --publisher-id pub_acme

# Generate a signed payload (pass the output to your server instead of calling the SDK)
sentinelid-sim payload --publisher-id pub_acme --game-id game_fps_01

The simulator calls POST /v1/device/sim/register which is only available in the sandbox environment. Attempting to register a simulated device in production will be rejected. See the Device Simulator page for full subcommand reference and CI/CD usage.

Getting Started

Core Concepts

SDKs

Dashboard

Device VID / PID

Installation

Enumerate Devices

Open a Device and Request a Check

Open a Specific Device

DeviceCheckRequest Fields

HID Protocol

Write (host → device)

Read (device → host)

Sandbox Testing

​Device VID / PID

​Installation

​Enumerate Devices

​Open a Device and Request a Check

​Open a Specific Device

​DeviceCheckRequest Fields

​HID Protocol

​Write (host → device)

​Read (device → host)

​Sandbox Testing

Device VID / PID

Installation

Enumerate Devices

Open a Device and Request a Check

Open a Specific Device

DeviceCheckRequest Fields

HID Protocol

Write (host → device)

Read (device → host)

Sandbox Testing