Redeem the emailed code for a verification token

Changed on

Exchanges the 8-character code for a verification_token, sent as X-Email-Verification-Token on POST /invoices. The token is reusable for ~30 minutes for the same sender email. Attempts are capped: the fifth failure of any kind revokes the challenge (subsequent polls of the snapshot endpoint report revoked) and the user must request a new code. A caller that sends the challenge's poll_secret in x-scribo-verification-secret is told a dead challenge apart (410); everyone else gets the uniform 400, so a challenge id alone reveals nothing about the address. Sustained attempts are additionally throttled per source IP and per target mailbox. The token is returned to this caller only: the challenge's snapshot and event stream report expired after a code redeem, and open streams end.

post/api/v1/scribo/email-verifications/{id}/redeem

Request

Path parameters

idstring uuid required

Challenge UUID

Headers

x-scribo-verification-secretstring

Optional. The poll_secret returned by POST /api/v1/scribo/email-verifications. It never affects whether the code redeems; with a valid one, a challenge that can no longer be redeemed answers 410 verification_revoked instead of the uniform 400.

Request body

codestring required

Response

Code accepted

verification_tokenstring required
expires_atstring date-time required

Changes

    • info

      added the new optional header request parameter x-scribo-verification-secret

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status