--- title: Host Mutual Authentication description: Host Mutual Authentication --- [Skip to content](https://portal.sandgrain.eu/knowledge-base/host-mutual-authentication#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 Mutual Authentication ![token-mutual-authentication-flow](https://portal.sandgrain.eu/hubfs/token-mutual-authentication-flow.svg) Host mutual authentication verifies the identity of the **host** in the authentication exchange. Where token mutual authentication has the server challenge the device, this flow lets the device submit the host's challenge word (HCW) and host response word (HRW) so the server can validate them and return the outcome. The flow uses two endpoints, called in sequence: 1. **`POST /api/device/requestHostMutualAuth`** — submit the device's TID together with the host challenge word (HCW) and host response word (HRW). The server returns a `transactionId` that ties the flow together. 2. **`GET /api/device/checkHostMutualStatus`** — poll this endpoint with the `transactionId` to retrieve the authentication result. 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 host mutual authentication Submit the device token ID (TID) along with the host challenge word (HCW) and host response word (HRW). The response returns a `transactionId` used to check the authentication status. #### **Request** ``` POST /api/device/requestHostMutualAuth Content-Type: application/json CF-Access-Client-Id: CF-Access-Client-Secret: ``` #### **Request body** ``` { "requestSignedResponse": false, "TID": "800000001000000010000000000000014464b592da61f3fd5506fcb1f37f4bef", "HCW": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "HRW": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" } ``` | Field | Type | Description | | --- | --- | --- | | `TID` | string | The device token ID. Must be exactly **64 characters** long. | | `HCW` | string | The host challenge word. | | `HRW` | string | The host response word. | | `requestSignedResponse` | boolean | Set to `true` to request a signed response. | #### **Response — `201 Created`** ``` { "transactionId": "123e4567-e89b-12d3-a456-426614174000" } ``` | Field | Type | Description | | --- | --- | --- | | `transactionId` | string (UUID) | Identifies this authentication process. Use it to check the result in Step 2. | #### **Errors** | Code | Meaning | | --- | --- | | `400 Bad Request` | The request body is invalid — for example, `"TID must be exactly 64 characters long"`. | | `401 Unauthorized` | Authentication failed. | | `403 Forbidden` | Invalid request, commonly caused by an invalid Cloudflare Access token. | --- ### Step 2 — Check the host authentication result Poll this endpoint with the `transactionId` to retrieve the outcome of the host mutual authentication exchange. #### **Request** ``` GET /api/device/checkHostMutualStatus?transactionId= CF-Access-Client-Id: CF-Access-Client-Secret: ``` #### **Query parameters** | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `transactionId` | string (UUID) | Yes | The transaction ID identifying the authentication process. | | `requestSignedResponse` | boolean | No | Request a signed response. | #### **Response — `200 OK`** ``` { "status": [ "AUTH_OK", "AUTH_NOT_OK", "CLAIM_TOKEN" ], "claimTokenId": "123e4567-e89b-12d3-a456-426614174000", "HRW2": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ``` | Field | Type | Description | | --- | --- | --- | | `status` | string | The result of the authentication process. See possible values below. | | `claimTokenId` | string (UUID) | The claim token ID, returned when the status is `CLAIM_TOKEN`. | | `HRW2` | string | A hash of the server's response word, used by the device for the final verification step. | #### **Status values** | Value | Meaning | | --- | --- | | `AUTH_OK` | Host mutual authentication succeeded. | | `AUTH_NOT_OK` | Host mutual authentication failed. | | `CLAIM_TOKEN` | A token is ready to be claimed; use the returned `claimTokenId`. | #### **Errors** | Code | Meaning | | --- | --- | | `401 Unauthorized` | Authentication failed. | | `403 Forbidden` | Invalid request, commonly caused by an invalid Cloudflare Access token. | --- ### Related articles - 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 - Claiming a token after `CLAIM_TOKEN` - [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