When to Use Custom Authentication
Email link authentication works well for simple use cases but has some limitations:- You cannot access the ceremony URL to send via other channels.
- It interrupts your application’s flow because recipients must check their email.
- You cannot control when or how the email is sent.
- Share with recipients via email or SMS.
- Redirect recipients directly to the ceremony.
- Embed into your application.
Ceremony Creation
To use custom authentication, create an envelope and set the recipient’sceremony_creation
to manual
.
Example API request:

authentication_type
set to custom
.
Provide the following authentication data:
provider
: The name of the application or company authenticating the recipient.data
: Key-value pairs containing details like timestamps or session IDs.

data
should clearly link to the recipient’s authentication session in your system.
Keep logs and session details that can easily link the recipient’s identity to the envelope.
For more details, see our Terms & Conditions.
Authentication Provider
Set the provider property to the name of the company or app authenticating the recipient. It will be included as-is in the audit log, like this:John Doe has been authenticated by [Provider Name]
Custom Authentication Data
Thedata
property contains key-value pairs with authentication details. These details appear in the envelope’s audit log and help link the ceremony to the authentication session in your system.
In special cases, such as legal proceedings, you may need to provide your internal records to confirm that the recipient was properly authenticated.
Good examples of authentication data include:
- Session Data: Recommended for linking recipient sessions in your system to the ceremony. Include Session IDs and session start timestamps.
- User Identification: If sending URLs by email, include recipient emails. If using SMS, include recipient phone numbers. You can also include unique user IDs from your system.
- Authentication Event Details: Clarify the method used, such as OTP or biometrics, and add device IDs, IP addresses, or geolocation data.
- Other Data: Hashes, nonces, transaction IDs, or other unique references.
Session ID: a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3
Order Reference: 25005
Authentication Timestamp: 2025-12-31T10:00:00Z
Authentication Method: SMS
Phone Number: +1-111-1111111
Using the Ceremony URL
After creating a custom-authenticated ceremony, you receive the Ceremony URL. With this URL, you can:- Send customized emails with your branding and domain.
- Embed the ceremony into your application.
- Redirect recipients from your application directly to the ceremony.
Audit Log
When recipients access a ceremony using custom authentication, the timestamp,provider
, and authentication data
are recorded in the Audit Log.

Next Steps
- Learn how to embed the ceremony.
- Review our Terms & Conditions.