πŸͺ›API Doc - Optional Response Signing

AllScale Open API Version: v1 Last updated: 2026-01-21


Overview

Applies only when signed_response = true for the store


AllScale supports optional response signing to allow clients to verify:

  • Response authenticity

  • Payload integrity

  • Request–response binding

  • Protection against replayed or substituted responses

Response signing is disabled by default.

It becomes active only when the store is created or configured with:

signed_response = true

When Response Signing Is Enabled

When enabled, every API response includes additional headers that allow the client to verify the response cryptographically.


Response Headers

Header
Required
Description

X-Response-Timestamp

Yes

Unix timestamp (seconds) generated by server

X-Response-Nonce

Yes

Unique nonce generated per response

X-Response-Signature

Yes

HMAC signature of the response

X-Request-Nonce

Recommended

Echo of request nonce

X-Request-Id

Yes

Unique request identifier


Response Canonical String

When signed_response = true, the response signature is computed using:

Each field is joined using newline characters (\n).


Field Definitions

Field
Description

STATUS_CODE

HTTP status code (e.g. 200)

PATH

Request path (e.g. /v1/payments)

REQUEST_NONCE

X-Nonce from the request

REQUEST_BODY_SHA256

SHA256 hash of raw request body

RESPONSE_TIMESTAMP

Server timestamp

RESPONSE_NONCE

Random nonce generated per response

RESPONSE_BODY_SHA256

SHA256 hash of raw response body

⚠️ Important: Hashes must be calculated using the exact raw request / response body bytes.


Response Signature Algorithm

Algorithm

Encoding

Formula

Header format


Response Example

Response Headers

Response Body


Client Verification Steps

  1. Extract headers:

  • X-Response-Timestamp

  • X-Response-Nonce

  • X-Response-Signature

  • X-Request-Nonce

  1. Compute:

  • REQUEST_BODY_SHA256

  • RESPONSE_BODY_SHA256

  1. Rebuild canonical string:

  1. Compute:

  1. Compare:

  1. Validate:

  • Timestamp within Β±5 minutes

  • Response nonce not reused


Postman Response Verification Script

Place this in Postman β†’ Tests tab


Replay Protection

Responses are protected using:

  • Timestamp validation (Β±5 minutes)

  • Unique response nonce

  • Request–response binding via request nonce

  • Optional nonce replay cache on client side


Error Handling

Even error responses are signed.

Example:

Clients must still verify the response signature before trusting the error.


Important Notes

βœ” When Response Signing Is Enabled

  • Client must verify signature

  • Client must validate timestamp

  • Client should cache nonces

  • Client must reject mismatched responses

βœ” When Response Signing Is Disabled

  • No X-Response-* headers are returned

  • Client should skip verification

  • Suitable for:

    • Internal testing

    • Low-risk integrations

    • Legacy compatibility


Best Practices

  • Always verify response signature before processing data

  • Cache response nonces for at least 5 minutes

  • Reject responses with invalid timestamps

  • Use raw response body for hashing

  • Log request_id for debugging

  • Never disable verification in production


End of document.

Last updated