--- title: Host Response Word Request with Ephemeral Key (EK) description: Host Response Word Request with Ephemeral Key (EK) --- [Skip to content](https://portal.sandgrain.eu/knowledge-base/api/host-response-word-request-with-ephemeral-key-ek#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 with Ephemeral Key (EK) ![host-response-word-request-ek-flow](https://portal.sandgrain.eu/hs-fs/hubfs/host-response-word-request-ek-flow.png?width=670&height=452&name=host-response-word-request-ek-flow.png) This flow is the ephemeral-key variant of the **Host Response Word Request** flow. It requests a **host response word (HRW)** for a given **host challenge word (HCW)**, and additionally returns an **ephemeral key (EK)** encrypted for a public key you supply in the request. The difference from the standard flow is: - The request includes a **`recipientPublicKey`** (a PEM-encoded RSA public key). The ephemeral key is protected for this recipient. - The status response returns an extra **`EK`** field alongside the HRW once generation succeeds. The flow uses two endpoints, called in sequence: 1. **`POST /api/device/EKRequestHRW`** — submit the device's TID, the host challenge word (HCW), and the `recipientPublicKey`. The server returns a `transactionId`. 2. **`GET /api/device/EKCheckRequestHRWStatus`** — poll this endpoint with the `transactionId` until the HRW and EK have 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 with an ephemeral key Submit the device token ID (TID), the host challenge word (HCW), and the recipient's public key. The response returns a `transactionId` used to check the generation status. #### **Request** ``` POST /api/device/EKRequestHRW Content-Type: application/json CF-Access-Client-Id: CF-Access-Client-Secret: ``` #### **Request body** ``` { "requestSignedResponse": false, "recipientPublicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...\n-----END PUBLIC KEY-----", "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. | | `recipientPublicKey` | string | A PEM-encoded RSA public key. The ephemeral key (EK) is protected for this recipient. | | `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 and ephemeral key. Keep polling while the status is `PROCESSING` or `NOT_READY`; the HRW and EK are returned once the status is `GENERATED_HRW`. #### **Request** ``` GET /api/device/EKCheckRequestHRWStatus?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", "EK": "cccccccccccccccccccccccccccccccc" } ``` | 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`. | | `EK` | string | The ephemeral key, protected for the `recipientPublicKey` supplied in Step 1. 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 or EK will be generated. | | `GENERATED_HRW` | The host response word and ephemeral key have been generated and are returned in the `HRW` and `EK` fields. | #### **Errors** | Code | Meaning | | --- | --- | | `401 Unauthorized` | Authentication failed. | | `403 Forbidden` | Invalid request, commonly caused by an invalid Cloudflare Access token. | --- ### Related articles - Host Response Word Request — the standard flow without an ephemeral key (`requestHRW`, `checkRequestHRWStatus`) - 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` - [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