Skip to main content
With custom authentication, your application or workflow authenticates the recipient. SignatureAPI provides a ceremony URL that you share directly with the recipient to start their signing session.

​
When to use

Custom authentication is the right choice when:
  • Recipients are already authenticated in your system.
  • You want to integrate signing into your existing application flow.
  • You need specific authentication methods (biometrics, SSO, multi-factor).
  • You want to embed the ceremony in your application.
After creating the ceremony, you can:
  • Send the URL via email or SMS with your own branding.
  • Redirect the recipient directly to the ceremony.
  • Embed the ceremony in your application interface.
  • Include the URL in push notifications.

​
Creating a custom authentication ceremony

​
On envelope creation (automatic)

Set the recipient’s ceremony authentication to custom when creating the envelope. Include your authentication details in the provider and data properties.
Custom authentication ceremony on envelope creation
// 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": "2025-12-31T23:59:59Z"
                        }
                    }
                ]
            }
        }
    ],
    "documents": [ /* ... */ ]
}
The response includes ceremony.url for each recipient:
Response (excerpt)
{
    "id": "abcdef12-3456-7890-1234-abcdef123456",
    "title": "Service Agreement",
    "recipients": [
        {
            "type": "signer",
            "key": "client",
            "ceremony": {
                "authentication": [
                    {
                        "type": "custom",
                        "provider": "SuperApp",
                        "data": {
                            "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
                            "Authenticated At": "2025-12-31T23:59:59Z"
                        }
                    }
                ],
                "url": "https://sign.signatureapi.com/en/start?token=eyJhbGcNiIsInR..."
            }
        }
    ]
}

​
Create Ceremony endpoint (manual)

Use the Create Ceremony endpoint to create a custom authentication ceremony after the envelope is created.
Creating a new ceremony automatically revokes any previous ceremony for that recipient. Only the most recent ceremony remains active.
Create custom authentication ceremony
// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/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": "2025-12-31T23:59:59Z"
      }
    }
  ]
}
The url property in the response is the ceremony URL to deliver to the recipient.
Response
// HTTP Status Code 201

{
  "authentication": [
    {
      "type": "custom",
      "provider": "SuperApp",
      "data": {
        "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
        "Authenticated At": "2025-12-31T23:59:59Z"
      }
    }
  ],
  "embeddable_in": [],
  "redirect_url": null,
  "redirect_delay": 3,
  "url_variant": "standard",
  "url": "https://sign.signatureapi.com/en/start?token=eyJhbGcNiIsInR..."
}

​
Authentication provider

Set provider to the name of the company or application that authenticated the recipient. This value appears in the audit log:
John Doe has been authenticated by [Provider Name]

​
Authentication data

The data property holds key-value pairs that link the ceremony to your authentication records. These values appear in the envelope audit log.
The values in data must be sufficient to verify how the recipient was authenticated. In edge cases such as legal proceedings, you may need to provide your internal records to confirm the recipient’s identity.When using custom authentication, retain all records necessary to prove authentication. Review our Terms & Conditions for details.
Useful data to include:
  • Session data: Session IDs and session start timestamps that link to your authentication records.
  • User identification: Email addresses, phone numbers, or user IDs from your system.
  • Authentication method: The method used (OTP, biometrics, SSO) and relevant details like device IDs or IP addresses.
  • Transaction references: Hashes, nonces, or other unique identifiers.
Example with rich authentication data: 
{
  "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"
  }
}
Review the values in data carefully. Do not include unnecessary sensitive information.

​
Using the ceremony URL

After creating the ceremony, you receive the URL. You can:
  • Send a customized email using your own domain and branding.
  • Embed the ceremony in your application.
  • Redirect the recipient from your application directly to the ceremony.
Treat ceremony URLs as sensitive credentials. Do not expose them in public forums or share them with unauthorized users.

​
Audit log

When a recipient accesses a ceremony using custom authentication, SignatureAPI records the timestamp, provider, and authentication data. The audit log entry looks like this:
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.