With custom authentication, your workflow or your app authenticate the recipient. SignatureAPI provides a URL you can share directly with recipients to start the signing ceremony.

​
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.

With custom authentication, you authenticate recipients yourself and share authentication details with SignatureAPI.

SignatureAPI sends you the ceremony URL, which you can:

  • 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’s ceremony_creation to manual.

Example API request:

{
  "title": "Dummy Agreement",
  "label": "Dummy Agreement for Order Ref. 25005",
  "documents": [
    //...
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "human",
      "name": "John Doe",
      "email": "john@example.com",
      "ceremony_creation": "manual"
    }
  ]
}

Use the recipient ID (from the envelope creation response) to create the ceremony with 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.

Example custom authentication request:

{
  "authentication": {
    "type": "custom",
    "provider": "SuperApp",
    "data": {
      "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
      "Authenticated At": "Dec 31, 2025 23:59:59"
    }
  }
}

The values provided in 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

The data 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.

Example:

{
  "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",
  "IP Address": "100.100.100.100"
}

Carefully check authentication data to avoid sending sensitive recipient details.

​
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.

Treat Ceremony URLs as sensitive data. Do not expose them in public forums or share them with unauthorized users.

​
Audit Log

When recipients access a ceremony using custom authentication, the timestamp, provider, and authentication data are recorded in the Audit Log.

​
Next Steps