payee_credential: No valid payee credential
A payee route (GET /payee/v1/destinations, POST /payee/v1/destinations, GET /payee/v1/vouchers, GET /payee/v1/receive, and the payee terms, task, recourse and off-ramp routes) needs to know which payee is calling, and the request did not prove it. The Authorization header carried neither of:
- a
Dynamo-Payee v2proof made for this request (owner-api 1.9.0): signed by the serviceNode key over the deployment's audience, the address, the method, the path with the canonical query, the body hash, a fresh nonce and the time, within 300 seconds of the deployment's clock (how to sign one); - a scoped payee credential (
Bearer …) minted for that serviceNode (not accepted onPOST /payee/v1/destinationsorPOST /payee/v1/offramps, which answer 403credential_scope).
When a Dynamo-Payee header was sent but refused, reason names the check instead of payee_credential:
reason | What was wrong |
|---|---|
payee_proof_v1 | an address-and-time (v1) proof; refused at every version: sign a v2 proof |
payee_proof_malformed | the header is not v2;payee=…;aud=…;ts=…;nonce=…;body=…;sig=… |
payee_proof_stale | issued more than 300 seconds from the deployment's clock |
payee_proof_audience | made for another deployment or tenant |
payee_proof_body | the body hash does not match the body received |
payee_proof_replayed | the nonce was already used |
payee_signature | not signed by the payee's key for this method, path and body |
Nothing was read or changed. A scoped credential of another kind answers 403 credential_scope instead.
On the hosted tier, Authorization carries the tenant's API key (Bearer …) and the payee proof goes in a separate Dynamo-Payee header; the front door forwards it to the payee route. A proof sent in Authorization alone answers 401 unauthorized at the front door. A scoped payee credential may be sent as Bearer … in Authorization on its own.
What to do
- Sign a new
Dynamo-Payee v2proof for each call, over the exact method, path and body you send; a proof works once and expires after 300 seconds. - Check that the signing key is the serviceNode's own key and the address in the header is that serviceNode.
- Or ask the owner for a payee credential for this serviceNode.
On the wire
HTTP 401.
{
"error": "unauthorized",
"reason": "payee_credential",
"detail": "a fresh Dynamo-Payee signature by the serviceNode key is required (fail closed)"
}
The detail wording differs slightly between routes; the reason is the same.
See getting paid as a payee and all error codes.