Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

Host Authentication with Ephemeral Key (EK)

host-authentication-ek-flowThis flow performs standard field device authentication and returns an ephemeral key (EK) protected for a public key you supply in the request. On success it also provides a claim token that can be used to claim the associated token.

The device submits its TID together with the host challenge word (HCW) and host response word (HRW); the server validates them and, once authentication resolves, returns the result along with the EK.

The flow uses two endpoints, called in sequence:

  1. POST /api/device/EKRequestHostAuth — submit the device's TID, HCW, HRW, and the recipientPublicKey. The server returns a transactionId.
  2. GET /api/device/EKCheckRequestHostAuthStatus — poll this endpoint with the transactionId to retrieve the authentication result and the ephemeral key.

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 authentication with an ephemeral key

Submit the device token ID (TID), the host challenge word (HCW), the host response word (HRW), and the recipient's public key. The response returns a transactionId used to check the authentication status.

Request

POST /api/device/EKRequestHostAuth 
Content-Type: application/json 
CF-Access-Client-Id: <your-client-id> 
CF-Access-Client-Secret: <your-client-secret>

Request body

{   
     "requestSignedResponse": false,   
     "recipientPublicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...\n-----END PUBLIC KEY-----",   
     "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.
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 authentication 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 host authentication result

Poll this endpoint with the transactionId to retrieve the outcome of the authentication and the ephemeral key.

Request

GET /api/device/EKCheckRequestHostAuthStatus?transactionId=<transactionId> 
CF-Access-Client-Id: <your-client-id> 
CF-Access-Client-Secret: <your-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",   
     "claimTokenId": "123e4567-e89b-12d3-a456-426614174000",   
     "EK": "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.
EK string The ephemeral key, protected for the recipientPublicKey supplied in Step 1.

Status values

Value Meaning
AUTH_OK Authentication succeeded.
AUTH_NOT_OK 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

  • Host Response Word Request with Ephemeral Key (EK) — generating the HRW and EK (EKRequestHRW, EKCheckRequestHRWStatus)
  • Host Mutual Authentication — the standard host auth flow without an ephemeral key (requestHostMutualAuth, checkHostMutualStatus)
  • Cloudflare Access service tokens — generating your CF-Access-Client-Id and CF-Access-Client-Secret
  • Claiming a token after CLAIM_TOKEN