--- title: Host Response Word Request description: Request RW --- [Skip to content](https://portal.sandgrain.eu/knowledge-base/api/request-rw#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. [API Documentation](https://portal.sandgrain.eu/knowledge-base/api-documentation?hsLang=en) 3. [Device API Integration](https://portal.sandgrain.eu/knowledge-base/api-documentation?hsLang=en#device-api-integration) October 6, 2026 # Host Response Word Request ![host-response-word-request-flow](https://portal.sandgrain.eu/hs-fs/hubfs/host-response-word-request-flow.png?width=670&height=435&name=host-response-word-request-flow.png)This flow requests a **host response word (HRW)** for a given **host challenge word (HCW)**. The device submits its TID and the HCW, and the server generates the corresponding HRW. Because generation is asynchronous, you request it first and then poll for the result. The flow uses two endpoints, called in sequence: 1. **`POST /api/device/requestHRW`** — submit the device's TID and the host challenge word (HCW). The server returns a `transactionId` that ties the flow together. 2. **`GET /api/device/checkRequestHRWStatus`** — poll this endpoint with the `transactionId` until the HRW has been generated. Every request must be authenticated at the edge with Cloudflare Access headers (see below). Authentication headers Both endpoints require the following Cloudflare Access service-token headers on every request: | Header | Required | Description | | --- | --- | --- | | `CF-Access-Client-Id` | Yes | Your Cloudflare Access client ID. | | `CF-Access-Client-Secret` | Yes | Your Cloudflare Access client secret. | If these headers are missing or invalid, the request is rejected with `403 Forbidden`. --- ### Step 1 — Request a host response word (HRW) Submit the device token ID (TID) and the host challenge word (HCW). The response returns a `transactionId` used to check the generation status. #### **Request** ``` POST /api/device/requestHRW Content-Type: application/json CF-Access-Client-Id: CF-Access-Client-Secret: ``` #### **Request body** ``` { "requestSignedResponse": false, "TID": "800000001000000010000000000000014464b592da61f3fd5506fcb1f37f4bef", "HCW": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ``` | Field | Type | Description | | --- | --- | --- | | `TID` | string | The device token ID. Must be exactly **64 characters** long. | | `HCW` | string | The host challenge word for which to generate a host response word. | | `requestSignedResponse` | boolean | Set to `true` to request a signed response. | #### **Response — `200 OK`** ``` { "transactionId": "123e4567-e89b-12d3-a456-426614174000" } ``` | Field | Type | Description | | --- | --- | --- | | `transactionId` | string (UUID) | Identifies this request process. Use it to check the result in Step 2. | **Errors** | Code | Meaning | | --- | --- | | `401 Unauthorized` | Authentication failed. | | `403 Forbidden` | Invalid request, commonly caused by an invalid Cloudflare Access token. | --- ### Step 2 — Check the HRW request result Poll this endpoint with the `transactionId` to retrieve the generated host response word. Keep polling while the status is `PROCESSING` or `NOT_READY`; the HRW is returned once the status is `GENERATED_HRW`. #### **Request** ``` GET /api/device/checkRequestHRWStatus?transactionId= CF-Access-Client-Id: CF-Access-Client-Secret: ``` #### **Query parameters** | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `transactionId` | string (UUID) | Yes | The transaction ID identifying the request process. | | `requestSignedResponse` | boolean | No | Request a signed response. | #### **Response — `200 OK`** ``` { "status": "GENERATED_HRW", "HRW": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" } ``` | Field | Type | Description | | --- | --- | --- | | `status` | string | The current state of the HRW request. See possible values below. | | `HRW` | string | The generated host response word. Returned when the status is `GENERATED_HRW`. | #### **Status values** | Value | Meaning | | --- | --- | | `PROCESSING` | The request is being processed. Continue polling. | | `NOT_READY` | The result is not ready yet. Continue polling. | | `AUTH_NOT_OK` | Authentication failed; no HRW will be generated. | | `GENERATED_HRW` | The host response word has been generated and is returned in the `HRW` field. | #### **Errors** | Code | Meaning | | --- | --- | | `401 Unauthorized` | Authentication failed. | | `403 Forbidden` | Invalid request, commonly caused by an invalid Cloudflare Access token. | --- ### Related articles - Host Mutual Authentication — submitting HCW/HRW for host verification (`requestHostMutualAuth`, `checkHostMutualStatus`) - Token Mutual Authentication — the device-challenge flow (`requestMutualAuthCW`, `replyMutualAuthRW`, `checkMutualAuthStatus`) - Cloudflare Access service tokens — generating your `CF-Access-Client-Id` and `CF-Access-Client-Secret` - Device token IDs (TIDs) — format and provisioning | [← Priority Host Authentication with EK](https://portal.sandgrain.eu/knowledge-base/api/priority-host-authentication-with-ephemeral-key-ek?hsLang=en) | [Priority Host Response Word Request →](https://portal.sandgrain.eu/knowledge-base/api/priority-host-response-word-request?hsLang=en) | | --- | --- | - [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