Recipient authentication
Recipient Authentication
Choose how recipients verify their identity before accessing a signing ceremony.
Before a recipient can access a ceremony, they must authenticate. SignatureAPI supports three authentication methods that you can use individually or combine for added security.
Choose a method
Which authentication method should my recipient use?
See every path
Who delivers the ceremony link to the recipient?
- SignatureAPI, by email
Should the recipient also enter a code from their email before they see the documents?
- No, the link is enough
Email link (the default): SignatureAPI emails the recipient a direct link; opening it authenticates them. No setup: it is what you get when you leave out
ceremony. The ceremony'surlisnullbecause SignatureAPI delivers it. See: Email link authentication - Yes, add a second step
Email link, then email code: SignatureAPI emails the invitation link and, inside the ceremony, a 9-digit verification code, so your application sends neither email. The ceremony's
urlstaysnull. This is one of the two setups the HIPAA page describes for documents with protected health information. See: Multiple authentication methods, HIPAA
- No, the link is enough
- My application: my own email, SMS, an in-app link or an embedded ceremony
Has your application already authenticated the recipient?
- Yes, they are signed in to my application
Do you also want a second factor that SignatureAPI controls?
- No, my authentication is enough
Custom: Your application authenticates the recipient and SignatureAPI returns a ceremony URL to share or embed. Set
provideranddata: both appear in the audit log, and you must keep the records that prove how the recipient was authenticated. See: Custom authentication - Yes, add an email code
Custom, then email code: Your application authenticates the recipient first, then SignatureAPI independently checks their email with a 9-digit code inside the ceremony. The URL is returned and your application delivers it. See: Multiple authentication methods
- No, my authentication is enough
- No, SignatureAPI should check their email
Email code: The API returns the ceremony URL and you deliver it through your own channel. When the recipient opens it, SignatureAPI emails them a 9-digit code to enter before signing. See: Email code authentication, Ceremony URL
- Yes, they are signed in to my application
"ceremony": {
"authentication": [{ "type": "email_link" }]
}"ceremony": {
"authentication": [
{ "type": "email_link" },
{ "type": "email_code" }
]
}"ceremony": {
"authentication": [{ "type": "email_code" }]
}"ceremony": {
"authentication": [
{
"type": "custom",
"provider": "Your App",
"data": { "session_id": "..." }
}
]
}"ceremony": {
"authentication": [
{ "type": "custom", "provider": "Your App", "data": { "session_id": "..." } },
{ "type": "email_code" }
]
}Authentication methods
Email Link (default)
SignatureAPI sends the recipient an email with a direct link. Clicking the link authenticates the recipient automatically.
- No setup required. Works out of the box.
- Simplest experience for recipients.
- Ceremonies are created and emails sent automatically when you create an envelope.
- Your app to SignatureAPI: Create the envelope (default ceremony)
- SignatureAPI to Recipient: Invitation email with the link
- Recipient to SignatureAPI: Open the link
- Open the link
Opening the link authenticates the recipient. The ceremony
urlisnullin API responses.
Learn more about Email Link Authentication
Email Code
SignatureAPI sends the recipient an email with a 9-digit verification code. The recipient enters the code to authenticate.
- Confirms the recipient has access to their email account.
- As the first method, you receive the ceremony URL to share through your own channels, over SMS, app notifications, or direct links.
- After
email_link, SignatureAPI still emails the invitation and the code becomes a second step.
- Your app to SignatureAPI: Create the ceremony with
email_code - SignatureAPI to Your app: Ceremony
url - Your app to Recipient: Deliver the URL
- Recipient to SignatureAPI: Open the URL and ask for a code
- SignatureAPI to Recipient: Email with the 9-digit code
- Recipient to SignatureAPI: Enter the code
- Deliver the URL
Use your own email, SMS or in-app link.
Dashed: a reply, or an asynchronous call such as a webhook.
Learn more about Email Code Authentication
Custom
Your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share directly or embed in your application.
- Use your existing authentication systems.
- Supports embedded signing experiences.
- Your authentication details are recorded in the audit log.
- Your app to Recipient: Authenticate the recipient
- Your app to SignatureAPI: Create the ceremony with
custom - SignatureAPI to Your app: Ceremony
url - Your app to Recipient: Deliver or embed the URL
- Authenticate the recipient
Sign-in, SSO or any method you use.
- Create the ceremony with
customSend
provideranddatafor the audit log.
Dashed: a reply, or an asynchronous call such as a webhook.
Learn more about Custom Authentication
Multiple methods
Combine authentication methods for enhanced security. Recipients complete each method in sequence before accessing the ceremony.
The first method decides who delivers the ceremony URL, so [email_link, email_code] has SignatureAPI email the invitation link and the verification code, with no email sent by your application.
- Your app to SignatureAPI: Create the ceremony with
email_link,email_code - SignatureAPI to Recipient: Invitation email with the link
- Recipient to SignatureAPI: Open the link
- SignatureAPI to Recipient: Email with the 9-digit code
- Recipient to SignatureAPI: Enter the code
- Invitation email with the link
The first method decides delivery, so
urlstaysnulland your app sends nothing.
Learn more about Multiple Authentication Methods
How to create a ceremony
You can create a ceremony in two ways: automatically when creating an envelope, or manually using the Create Ceremony endpoint.
On envelope creation (automatic)
Pass a ceremony object on each recipient when creating an envelope. SignatureAPI creates the ceremony immediately.
If you omit ceremony, SignatureAPI uses email link authentication by default.
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Service Agreement",
"recipients": [
{
"type": "signer",
"key": "client",
"name": "John Doe",
"email": "john.doe@example.com"
}
],
"documents": [
{
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"places": [
{ "key": "client_signature", "type": "signature", "recipient_key": "client" }
],
"fixed_positions": [
{ "place_key": "client_signature", "page": 1, "top": 600, "left": 72 }
]
}
]
}POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Service Agreement",
"recipients": [
{
"type": "signer",
"key": "client",
"name": "John Doe",
"email": "john.doe@example.com",
"ceremony": {
"authentication": [
{
"type": "email_code"
}
]
}
}
],
"documents": [
{
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"places": [
{ "key": "client_signature", "type": "signature", "recipient_key": "client" }
],
"fixed_positions": [
{ "place_key": "client_signature", "page": 1, "top": 600, "left": 72 }
]
}
]
}POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Service Agreement",
"recipients": [
{
"type": "signer",
"key": "client",
"name": "John Doe",
"email": "john.doe@example.com",
"ceremony": {
"authentication": [
{
"type": "custom",
"provider": "SuperApp",
"data": {
"Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
"Logged In At": "2026-12-31T23:59:59Z"
}
}
]
}
}
],
"documents": [
{
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"places": [
{ "key": "client_signature", "type": "signature", "recipient_key": "client" }
],
"fixed_positions": [
{ "place_key": "client_signature", "page": 1, "top": 600, "left": 72 }
]
}
]
}POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Service Agreement",
"recipients": [
{
"type": "signer",
"key": "client",
"name": "John Doe",
"email": "john.doe@example.com",
"ceremony": {
"authentication": [
{
"type": "custom",
"provider": "SuperApp",
"data": {
"Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
"Logged In At": "2026-12-31T23:59:59Z"
}
},
{
"type": "email_code"
}
]
}
}
],
"documents": [
{
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"places": [
{ "key": "client_signature", "type": "signature", "recipient_key": "client" }
],
"fixed_positions": [
{ "place_key": "client_signature", "page": 1, "top": 600, "left": 72 }
]
}
]
}Create Ceremony endpoint (manual)
Use the Create Ceremony endpoint after the envelope is created. This lets you change authentication methods or create new access for the same recipient.
Creating a new ceremony automatically revokes any previous ceremony for that recipient. Only the most recent ceremony remains active.
Common use cases:
- Switch from custom authentication to email link if the recipient hasn’t signed within a set time.
- Provide a new URL after the original one expires.
- Update ceremony settings like the redirect URL.
POST /v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/ceremonies HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"authentication": [
{
"type": "email_link"
}
]
}POST /v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/ceremonies HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"authentication": [
{
"type": "email_code"
}
]
}POST /v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/ceremonies HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"authentication": [
{
"type": "custom",
"provider": "SuperApp",
"data": {
"Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
"Logged In At": "2026-12-31T23:59:59Z"
}
}
]
}POST /v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/ceremonies HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"authentication": [
{
"type": "custom",
"provider": "SuperApp",
"data": {
"Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
"Logged In At": "2026-12-31T23:59:59Z"
}
},
{
"type": "email_code"
}
]
}