---
title: "Verify OTP before browser signing"
method: POST
path: "/api/envelopes/{envelope_id}/otp/verify"
---

# Verify OTP before browser signing

`POST /api/envelopes/{envelope_id}/otp/verify`

## Request

- Base URL: `https://free-sign.com`
- URL: `https://free-sign.com/api/envelopes/{envelope_id}/otp/verify`
- Auth: none declared. Required headers: `x-fsig-session-signature`, `x-fsig-session-nonce`, `x-fsig-session-timestamp`, `x-fsig-session-action`

Returns otp_challenge_id and otp_verified_at so the browser can bind OTP verification into the signed canonical payload. Idempotent: a repeated call with the same signer_id + email + otp_code returns the same verified_at, even after the OTP TTL has elapsed. Idempotency still requires the correct otp_code — signer_id alone is not a bearer token. Fresh (un-verified) calls additionally enforce expires_at and max_attempts. Requires the four session-binding headers (see x-fsig-session-* component parameters).

## Path parameters

- `envelope_id` string, required

## Headers

- `x-fsig-session-signature` string, required
- `x-fsig-session-nonce` string, required
- `x-fsig-session-timestamp` string, date-time, required
- `x-fsig-session-action` 'otp.request' | 'otp.verify' | 'sign' | 'seal' | 'platform-seal' | 'finalize' | 'webauthn.register' | 'webauthn.authenticate', required

## Request body

- object
  - `signer_id` string, required
  - `email` string, email, required
  - `otp_code` string, required

## Response `200`

OTP verified.

- object
  - `signer_id` string, required
  - `email_hmac` string, required
  - `otp_challenge_id` string, required
  - `otp_verified_at` string, date-time, required

## Other responses

- `400`: otp_mismatch / otp_expired / otp_not_found.
- `429`: otp_locked (attempts exceeded).

---

[API](https://skmtc.dev/free-sign/apis/freesign-free-e-signature-api.md) · [All operations](https://skmtc.dev/free-sign/apis/freesign-free-e-signature-api/llms.txt) · [OpenAPI document](https://skmtc.dev/free-sign/apis/freesign-free-e-signature-api/revisions/5d8e9854ab85?raw)