Request signing

Enhanced and Bank-grade integrations sign every request. The signature proves that the request came from you and wasn’t changed in transit, independently of TLS and of the bearer credential.

Phew uses the IETF standards: HTTP Message Signatures (RFC 9421) and Digest Fields (RFC 9530), so you can use an existing library instead of writing your own.

What’s signed

Component	Why
@method	Prevents a signed GET being replayed as a POST
@target-uri	Binds the signature to the host, path and query
content-digest	Covers the body (required when there’s a body)
authorization	Binds the signature to the credential
phew-merchant	Required when the header is present
idempotency-key	Required when the header is present

Signature parameters: created (Unix seconds, required), keyid (required), alg (required), and optionally nonce. Phew rejects signatures with created more than 5 minutes from our clock.

Supported algorithms

ecdsa-p256-sha256, ed25519 and rsa-pss-sha512. We register your public keys (or JWKS URL) during onboarding, and the keyid must match one of them.

Example

1. Compute the body digest.

   Content-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:

2. Build the signature base from the covered components, in order:

   "@method": POST
   "@target-uri": https://api.getphew.com/v1/policies
   "content-digest": sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
   "authorization": Bearer eyJhbGciOiJFUzI1NiIs...
   "idempotency-key": order-100482-policy
   "@signature-params": ("@method" "@target-uri" "content-digest" "authorization" "idempotency-key");created=1761220329;keyid="psp-2026-10";alg="ecdsa-p256-sha256"

3. Sign the base with your private key and send the signature with its parameters:

   POST /v1/policies HTTP/1.1
   Host: api.getphew.com
   Authorization: Bearer eyJhbGciOiJFUzI1NiIs...
   Idempotency-Key: order-100482-policy
   Content-Type: application/json
   Content-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
   Signature-Input: phew=("@method" "@target-uri" "content-digest" "authorization" "idempotency-key");created=1761220329;keyid="psp-2026-10";alg="ecdsa-p256-sha256"
   Signature: phew=:MEUCIQDkNz0x1Hk3...:

Tip

The signature label must be phew. Sandbox returns a detailed signature_invalid error with the signature base we computed, so you can compare it with yours. Live never echoes it.

Verification errors

Status	error	Cause
401	signature_missing	Signing is required for this credential and no signature was sent
401	signature_invalid	The signature didn’t verify, or a required component wasn’t covered
401	signature_expired	created is outside the 5-minute window
400	digest_mismatch	Content-Digest doesn’t match the body
401	unknown_key	keyid isn’t registered for this client