POST /v1/keys/signature-check

Check this request signature

Access

Authenticated (self)

Cost

Free

Rate limit

60 / minute per account

Quota

None

Verify the RFC 9421 signature on THIS request against the calling key's own registered signers and echo a structured verdict: whether a signer matched, which components were covered, whether the body digest is valid, the created/expires/skew window, and PASS or FAIL with a reason. This is the integrator's debugging endpoint for Web Bot Auth. It only ever inspects the caller's own key and never reveals any other key's data. Sign the request the same way you would sign a real call.

Responses

200 The structured signature verdict for this request
- keyId string | null required
  
  The key that made this request. Null when the caller is a session rather than a key.
- verdict string required
  
  Whether this request’s signature would be accepted. `fail` is a normal, non-error response here: this endpoint returns 200 and tells you what is wrong.
  
  passfail
- reason string | null required
  
  Why the signature failed, in plain words. Null on a pass.
- signerThumbprint string | null required
  
  The RFC 7638 thumbprint of the signer that matched, which is the `keyid` your signature carried. Null when none matched.
- components array of string required
  
  The covered components the signature actually signed. `@method` and `@path` are always required, and `content-digest` is required on a mutating verb.
- digestValid boolean required
  
  Whether the body actually matches its Content-Digest header. Checked independently of the signature, because a signature only proves the HEADER was signed, not that it describes the body you sent.
- created string | null required
  
  The signature’s `created` time, as an ISO 8601 instant. Null when absent.
- expires string | null required
  
  The signature’s `expires` time, as an ISO 8601 instant. The window must be at most five minutes.
- skewMs number | null required
  
  How far the `created` time sits in the future relative to the server clock, in milliseconds. Up to 30 seconds is tolerated; beyond that the signature is rejected.
401 No or invalid credential
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at the credit top-up).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.