--- title: SDK API Reference description: SDK API Reference --- [Skip to content](https://portal.sandgrain.eu/knowledge-base/sdk-api-reference#main-content) English Show submenu for translations ![SandGrain\_Logo\_RGB\_white-bijgesneden (1)](https://portal.sandgrain.eu/hs-fs/hubfs/SandGrain_Logo_RGB_white-bijgesneden%20(1).png?width=427&height=83&name=SandGrain_Logo_RGB_white-bijgesneden%20(1).png) Open main navigation Close main navigation - English Show submenu for translations - [Contact us](https://portal.sandgrain.eu/login) [Contact us](https://portal.sandgrain.eu/login?hsLang=en) How can we help you? - There are no suggestions because the search field is empty. 1. [Knowledge Base](https://portal.sandgrain.eu/knowledge-base?hsLang=en) 2. [SDK](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en) 3. [SandGrain SDK](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en#sandgrain-sdk) October 6, 2026 # SDK API Reference **Who this is for:** Developers writing against the SandGrain SDK once it's installed. **What you'll accomplish:** Look up status codes and the core functions for each mode. The client must **always check the return value** of SDK calls. Every function returns an `sgr_sdk_status_t`. ### Status codes (`sgr_sdk_status_t`) | Code | Meaning | | --- | --- | | `SGR_SDK_OK` | Operation completed successfully | | `SGR_SDK_ERROR` | Generic error | | `SGR_SDK_INVALID_PARAM` | Invalid parameter provided | | `SGR_SDK_NOT_READY` | SDK not ready | | `SGR_SDK_TOKEN_ERROR` | Error interacting with the crypto Token | | `SGR_SDK_CRC_ERROR` | Data integrity check failed | | `SGR_SDK_COMM_ERROR` | Communication error | | `SGR_SDK_TIMEOUT` | Operation timed out | | `SGR_SDK_INTERNAL_ERROR` | Internal error | | `SGR_SDK_AUTH_FAILED` | Authentication failed | | `SGR_SDK_NOT_REGISTERED` | Device not registered on the Gateway | | `SGR_SDK_REGISTRATION_FAILED` | Device registration attempt failed | | `SGR_SDK_NO_DATA` | No data available from Device | | `SGR_SDK_BUSY` | Operation in progress (keep looping) | ### Initialize (both modes) **`sgr_sdk_status_t SGR_SDK_Initialize(void)`** Initializes internal components and prepares the system for authentication. Must be called before any authentication function. In `GATEWAY_MODE` it additionally initializes the authentication database and registers all whitelisted devices before initializing the middleware; in `DEVICE_MODE` only the middleware is initialized. ### Device mode functions **`SGR_SDK_Authenticate_Via_GW(void)`** Performs the full device authentication flow via the Gateway; drives the middleware state machine to a final state. Blocks until complete. Returns `SGR_SDK_OK` / `SGR_SDK_AUTH_FAILED` / `SGR_SDK_COMM_ERROR` / `SGR_SDK_ERROR`. **`SGR_SDK_Verification_FW(const uint8_t *fw_data, uint32_t fw_size, uint8_t *fw_rw)`** Performs firmware verification over the provided image; the crypto chip derives a Response Word, which (with the result) is sent via the Gateway to the Server for validation. The computed RW is stored in `fw_rw` and is a prerequisite for `SGR_SDK_Installation`. Returns `SGR_SDK_OK`, `SGR_SDK_AUTH_FAILED` (FW\_NOK), `SGR_SDK_INVALID_PARAM`, `SGR_SDK_TOKEN_ERROR`, `SGR_SDK_COMM_ERROR`, `SGR_SDK_ERROR`. **`SGR_SDK_Installation(void)`** Requests installation authorization: sends the firmware Response Word obtained during a previous successful verification (in the same session) plus device credentials; the Gateway forwards to the Server, which authorizes or denies. Returns `SGR_SDK_OK` (authorized), `SGR_SDK_AUTH_FAILED` (denied), `SGR_SDK_TOKEN_ERROR`, `SGR_SDK_COMM_ERROR`, `SGR_SDK_ERROR`. ### Gateway mode functions **`SGR_SDK_Authentication_Token_To_Server(void)`** Token-to-Server authentication: requests a Challenge Word from the server, computes the Response Word with the secure Token, sends it back, and processes the result. All steps and retries are handled internally. **`SGR_SDK_Authentication_Server_To_Token(void)`** Server-to-Token (reverse) authentication: generates a Challenge Word from the Token, requests/validates the Response Word, and reports the result. Used in mutual authentication scenarios. **`SGR_SDK_GW_Run(void)`** Unified Gateway dispatcher: continuously polls all device channels (up to `MAX_DEVICES`) and routes each incoming request to the correct handler (device authentication, firmware verification, installation) based on frame type. **The recommended entry point for the Gateway application loop**, call it in a tight loop and keep looping on `SGR_SDK_BUSY`. Lower-level handlers (`SGR_SDK_GW_Handle_Device_Auth`, `SGR_SDK_GW_Handle_FW_Verification`, `SGR_SDK_GW_Handle_Installation`) remain available for explicit per-flow control. ### Middleware and events The middleware exposes mode-specific functions (`sgr_mw_init`, `sgr_mw_authenticate_via_gw`, `sgr_mw_authentication_token_to_server`, `sgr_mw_authentication_server_to_token`, `sgr_mw_gw_authenticate_device(int device_idx)`) returning state-machine statuses (`SGR_MW_OK`, `SGR_MW_AUTH_FAILED`, `SGR_MW_COMM_ERROR`, `SGR_MW_ERROR`). Events are surfaced over MQTT topics such as `sandgrain/v1/{tid}/cmd/run_auth`, `sandgrain/v1/+/status`, and `sandgrain/v1/+/gw_log`. - [User Documentation](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#main-content) - [Quick Starter Guide](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#quick-starter-guide) - [User Manual](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#user-manual) - [Whitepaper](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#whitepaper) - [Token Leaflet](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#token-leaflet) - [Claim Token Procedure](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#claim-token-procedure) - [Daisy Chain](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#daisy-chain) - [Release Note](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#release-note) - [Naming Convention](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#naming-convention) - [SandGrain SDK](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#sandgrain-sdk) - [TrustBridge](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#trustbridge) - [API Documentation](https://portal.sandgrain.eu/knowledge-base/api-documentation?hsLang=en#main-content) - [Device API Integration](https://portal.sandgrain.eu/knowledge-base/api-documentation?hsLang=en#device-api-integration) - [Daisy Chain and Attestation](https://portal.sandgrain.eu/knowledge-base/api-documentation?hsLang=en#daisy-chain-and-attestation) - [SDK](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en#main-content) - [Core Functions](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en#core-functions) - [SandGrain SDK](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en#sandgrain-sdk) [![SandGrain\_Logo\_RGB\_white-bijgesneden (1)-1](https://portal.sandgrain.eu/hs-fs/hubfs/SandGrain_Logo_RGB_white-bijgesneden%20(1)-1.png?width=427&height=83&name=SandGrain_Logo_RGB_white-bijgesneden%20(1)-1.png "SandGrain_Logo_RGB_white-bijgesneden (1)-1")](https://portal.sandgrain.eu/?hsLang=en) [mailto:email@email.com](mailto:email@email.com) Copyright © 2026, sandgrain.eu