Skip to main content
With custom authentication, your application handles identity verification before the recipient accesses the signing ceremony. SignatureAPI provides a ceremony URL that you deliver directly, so the recipient can start signing without any additional authentication step on the SignatureAPI side. This approach is useful when:
  • Recipients are already authenticated in your system.
  • You want to integrate signing into your existing application flow without interrupting the user experience.
  • You need a specific authentication method, such as biometrics, SSO, or multi-factor.
In this example, we will:
  1. Create an envelope with custom authentication on the recipient’s ceremony object.
  2. Set delivery_type to "none" so SignatureAPI does not send an invitation email.
  3. Get the ceremony URL from the response and redirect the authenticated user.

​
Create the Envelope

Set the recipient’s ceremony object with authentication set to custom. Provide:
  • provider: The name of your application or company. This appears in the audit log as: “John Doe has been authenticated by [provider]”.
  • data: Key-value pairs that link the signing event to your authentication records. These values are recorded in the envelope audit log.
Set delivery_type to "none" to prevent SignatureAPI from sending an invitation email. Your application is responsible for delivering the ceremony URL to the recipient. 
// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
// Content-Type: application/json

{
    "title": "Service Agreement",
    "documents": [
        {
            "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/dummy-nda.pdf",
            "places": [
                {
                    "key": "client_signature",
                    "type": "signature",
                    "recipient_key": "client"
                }
            ]
        }
    ],
    "recipients": [
        {
            "type": "signer",
            "key": "client",
            "name": "John Doe",
            "email": "john.doe@example.com",
            "delivery_type": "none",
            "ceremony": {
                "authentication": [
                    {
                        "type": "custom",
                        "provider": "My App",
                        "data": {
                            "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
                            "User ID": "usr_88620999344",
                            "Authenticated At": "2025-12-31T23:59:59Z"
                        }
                    }
                ]
            }
        }
    ]
}
Include enough data in the data object to verify how the recipient was authenticated. Useful values include session IDs, user IDs, authentication timestamps, and authentication methods. These values appear in the audit log and may be needed to confirm identity in legal proceedings.

​
Get the Ceremony URL

The response includes the ceremony URL in recipients[].ceremony.url. Because authentication is custom (not email_link), the URL is available directly in the response. 
// HTTP Status Code 201

{
    "id": "abcdef12-3456-7890-1234-abcdef123456",
    "title": "Service Agreement",
    "recipients": [
        {
            "id": "re_01jxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "signer",
            "key": "client",
            "name": "John Doe",
            "email": "john.doe@example.com",
            "delivery_type": "none",
            "ceremony": {
                "authentication": [
                    {
                        "type": "custom",
                        "provider": "My App",
                        "data": {
                            "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
                            "User ID": "usr_88620999344",
                            "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=eyJhbGciOiJFUzI1NiIsInR..."
            },
            //...
        }
    ],
    //...
}

​
Redirect to the Ceremony URL

Use the url from the ceremony object to redirect the recipient from your application to the signing ceremony. Because your application already authenticated the recipient, they land directly in the signing experience without any additional login step. 
https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR...
Treat ceremony URLs as sensitive credentials. Do not expose them in logs, public forums, or client-side code where unauthorized users could access them. Deliver the URL only to the authenticated recipient.
After the recipient completes signing, SignatureAPI records the authentication event in the envelope audit log, including the provider name and all key-value pairs from the data object.

​
Try It

Try this example in Postman using your test API key to create a free, non-binding test envelope. Test envelopes won’t send emails, but you can review them in your dashboard.

​
Keep Learning