Sign Recipient via API (Interface Signing)

The customer server completes signing on behalf of a signer using their Signing PIN (the signer does not enter the signing page).

• The signer must have a Signing PIN configured and must have accepted the ERSD disclosure toward the sender (first-time consent happens on the signing page / frontend); an error is returned if either is missing
• Idempotency: the Idempotency-Key header takes precedence over the body IdempotencyKey; sending neither is an error. Replaying the same key returns the previous successful result (IdempotentReplay=true)
• Asset resolution: signing controls not explicitly bound in Tabs use SignatureId / SealId as the default asset; at least one must be available. The signature/seal must belong to the signer
• envelopeId and recipientId are path parameters, not part of the body

Applicable controls & default assets

• This endpoint signs / seals on behalf of the signer and only covers signing-type controls (e.g. signHere, initialHere, stamp). It does not fill other data-entry controls (text / date / email / number, etc.); envelopes with such unfilled fields must first be completed on the signing page by the signer, otherwise a "field not filled" error is returned
• Tabs is optional — usually no per-control binding is needed: signing controls not listed in Tabs fall back to SignatureId (signature) or SealId (seal) as the default asset

Credential (JWE)

Encrypt the signing PIN with JWE (RFC7516): alg=RSA-OAEP-256, enc=A256GCM.

1. Public key: GET {baseUrl}/.well-known/jwks.json, take the use=enc key (keep its kid).
2. Plaintext payload:

{"typ":"sign_pin","secret":"<PIN>","context":{"userId":"<recipient UserId>","envelopeId":"<envelopeId in URL>","recipientId":"<recipientId in URL>"},"iat":<sec>,"exp":<iat+60>,"jti":"<uuid>"}

1. Encrypt to a 5-segment Compact string (protected.encryptedKey.iv.ciphertext.tag) and put it in Credential.

Notes: must be 5 segments (WebCrypto: split the trailing 16-byte tag into its own segment); header is the AAD; exp<=60s, jti single-use (re-sign on retry); context must match the recipient and URL.

Plaintext PIN: not accepted by default — contact us to enable it.