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 gives you complete control over the recipient verification process. You handle authentication within your application, then share the authentication details with SignatureAPI to create the ceremony. This approach is ideal when:
  • You want to integrate signing seamlessly into your existing application flow
  • Recipients are already authenticated in your system
  • You need to use specific authentication methods (biometrics, SSO, multi-factor authentication)
  • You want to control exactly when and how recipients access the ceremony
With custom authentication, SignatureAPI provides you with the ceremony URL that you can:
  • Share with recipients via email or SMS
  • Redirect recipients directly to the ceremony
  • Embed into your application interface
  • Include in push notifications or other communication channels

​
Ceremony Creation

You can create a custom authentication ceremony automatically when you create a ceremony, or manually at a later time.

​
On Envelope Creation (Automatic)

When creating an envelope, configure the recipient’s ceremony to use custom authentication. This automatically creates the ceremony and provides you with the ceremony URL in the response.
Custom Authentication Ceremony on Envelope Creation (Request)
// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
// 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",
                            "Authenticated At": "Dec 31, 2025 23:59:59"
                        }
                    }
                ]
                // optional properties: redirect_url, url_variant, embeddable_in, etc ...
            }
            //...
        }
    ],
    // ...
}
Custom Authentication Ceremony on Envelope Creation (Response)
{
    "id": "abcdef12-3456-7890-1234-abcdef123456",
    "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",
                            "Authenticated At": "Dec 31, 2025 23:59:59"
                        }
                    }
                ],
                "url": "https://sign.signatureapi.com/en/start?token=eyJhbGcNiIsInR..."
                //... 
            }
            //...
        }
    ],
    //...
}

​
Create Ceremony Endpoint (Manual)

To manually create a custom authentication ceremony, use the Create Ceremony endpoint.
When you create a new ceremony for a recipient, any previous ceremonies are automatically revoked. This ensures that only the most recent ceremony remains active and accessible.
Create Email Code Ceremony (Request)
// POST https://api.signatureapi.com/v1/recipients/rec_123/ceremonies
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "authentication": [
    {
      "type": "custom",
      "provider": "SuperApp",
      "data": {
        "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
        "Authenticated At": "Dec 31, 2025 23:59:59"
      }
    }
  ]
  // optional properties: redirect_url, url_variant, embeddable_in, etc ...
}
Create Email Code Ceremony (Response)
{
  "authentication": [
    {
      "type": "custom",
      "provider": "SuperApp",
      "data": {
        "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
        "Authenticated At": "Dec 31, 2025 23:59:59"
      }
    }
  ],
  "url": "https://sign.signatureapi.com/en/start?token=eyJhbGcNiIsInR..."
  //... 
}
The url property is the ceremony URL that you can share with recipients via your own channels (SMS, app notifications, direct links, etc).

​
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.
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.In special cases, such as legal proceedings, you may need to provide your internal records to confirm that the recipient was properly authenticated.For more details, see our Terms & Conditions.
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: 
{
  "type": "custom",
  "provider": "SuperApp",
  "data": {
    "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.
12/31/2025 11:59:59 PM
John Doe (#7161cf07) has been authenticated by SuperApp:
Session ID: a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3
Order Reference: 25005
Authenticated At: Dec 31, 2025 23:59:59
Authentication Method: SMS
Phone Number: +1-111-1111111
IP Address: 100.100.100.100
As provided by the initiator of the electronic signature transaction.