Skip to content

Recipient authentication

Recipient Authentication

Choose how recipients verify their identity before accessing a signing ceremony.

Before a recipient can access a ceremony, they must authenticate. SignatureAPI supports three authentication methods that you can use individually or combine for added security.

Choose a method

Which authentication method should my recipient use?

See every path

Who delivers the ceremony link to the recipient?

  • SignatureAPI, by email

    Should the recipient also enter a code from their email before they see the documents?

    • No, the link is enough

      Email link (the default): SignatureAPI emails the recipient a direct link; opening it authenticates them. No setup: it is what you get when you leave out ceremony. The ceremony's url is null because SignatureAPI delivers it. See: Email link authentication

    • Yes, add a second step

      Email link, then email code: SignatureAPI emails the invitation link and, inside the ceremony, a 9-digit verification code, so your application sends neither email. The ceremony's url stays null. This is one of the two setups the HIPAA page describes for documents with protected health information. See: Multiple authentication methods, HIPAA

  • My application: my own email, SMS, an in-app link or an embedded ceremony

    Has your application already authenticated the recipient?

    • Yes, they are signed in to my application

      Do you also want a second factor that SignatureAPI controls?

      • No, my authentication is enough

        Custom: Your application authenticates the recipient and SignatureAPI returns a ceremony URL to share or embed. Set provider and data: both appear in the audit log, and you must keep the records that prove how the recipient was authenticated. See: Custom authentication

      • Yes, add an email code

        Custom, then email code: Your application authenticates the recipient first, then SignatureAPI independently checks their email with a 9-digit code inside the ceremony. The URL is returned and your application delivers it. See: Multiple authentication methods

    • No, SignatureAPI should check their email

      Email code: The API returns the ceremony URL and you deliver it through your own channel. When the recipient opens it, SignatureAPI emails them a 9-digit code to enter before signing. See: Email code authentication, Ceremony URL

Authentication methods

SignatureAPI sends the recipient an email with a direct link. Clicking the link authenticates the recipient automatically.

  • No setup required. Works out of the box.
  • Simplest experience for recipients.
  • Ceremonies are created and emails sent automatically when you create an envelope.

Learn more about Email Link Authentication

Email Code

SignatureAPI sends the recipient an email with a 9-digit verification code. The recipient enters the code to authenticate.

  • Confirms the recipient has access to their email account.
  • As the first method, you receive the ceremony URL to share through your own channels, over SMS, app notifications, or direct links.
  • After email_link, SignatureAPI still emails the invitation and the code becomes a second step.
Email code
Your app
SignatureAPI
Recipient
  1. Your app to SignatureAPI: Create the ceremony with email_code
  2. SignatureAPI to Your app: Ceremony url
  3. Your app to Recipient: Deliver the URL
  4. Recipient to SignatureAPI: Open the URL and ask for a code
  5. SignatureAPI to Recipient: Email with the 9-digit code
  6. Recipient to SignatureAPI: Enter the code
  1. Deliver the URL

    Use your own email, SMS or in-app link.

Dashed: a reply, or an asynchronous call such as a webhook.

Learn more about Email Code Authentication

Custom

Your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share directly or embed in your application.

  • Use your existing authentication systems.
  • Supports embedded signing experiences.
  • Your authentication details are recorded in the audit log.
Custom
Your app
SignatureAPI
Recipient
  1. Your app to Recipient: Authenticate the recipient
  2. Your app to SignatureAPI: Create the ceremony with custom
  3. SignatureAPI to Your app: Ceremony url
  4. Your app to Recipient: Deliver or embed the URL
  1. Authenticate the recipient

    Sign-in, SSO or any method you use.

  2. Create the ceremony with custom

    Send provider and data for the audit log.

Dashed: a reply, or an asynchronous call such as a webhook.

Learn more about Custom Authentication

Multiple methods

Combine authentication methods for enhanced security. Recipients complete each method in sequence before accessing the ceremony.

The first method decides who delivers the ceremony URL, so [email_link, email_code] has SignatureAPI email the invitation link and the verification code, with no email sent by your application.

Email link, then email code
Your app
SignatureAPI
Recipient
  1. Your app to SignatureAPI: Create the ceremony with email_link, email_code
  2. SignatureAPI to Recipient: Invitation email with the link
  3. Recipient to SignatureAPI: Open the link
  4. SignatureAPI to Recipient: Email with the 9-digit code
  5. Recipient to SignatureAPI: Enter the code
  1. Invitation email with the link

    The first method decides delivery, so url stays null and your app sends nothing.

Learn more about Multiple Authentication Methods

How to create a ceremony

You can create a ceremony in two ways: automatically when creating an envelope, or manually using the Create Ceremony endpoint.

On envelope creation (automatic)

Pass a ceremony object on each recipient when creating an envelope. SignatureAPI creates the ceremony immediately.

If you omit ceremony, SignatureAPI uses email link authentication by default.

Email Link (default)
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
    "title": "Service Agreement",
    "recipients": [
        {
            "type": "signer",
            "key": "client",
            "name": "John Doe",
            "email": "john.doe@example.com"
        }
    ],
    "documents": [
        {
            "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
            "places": [
                { "key": "client_signature", "type": "signature", "recipient_key": "client" }
            ],
            "fixed_positions": [
                { "place_key": "client_signature", "page": 1, "top": 600, "left": 72 }
            ]
        }
    ]
}
Email Code
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
    "title": "Service Agreement",
    "recipients": [
        {
            "type": "signer",
            "key": "client",
            "name": "John Doe",
            "email": "john.doe@example.com",
            "ceremony": {
                "authentication": [
                    {
                        "type": "email_code"
                    }
                ]
            }
        }
    ],
    "documents": [
        {
            "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
            "places": [
                { "key": "client_signature", "type": "signature", "recipient_key": "client" }
            ],
            "fixed_positions": [
                { "place_key": "client_signature", "page": 1, "top": 600, "left": 72 }
            ]
        }
    ]
}
Custom
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
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",
                            "Logged In At": "2026-12-31T23:59:59Z"
                        }
                    }
                ]
            }
        }
    ],
    "documents": [
        {
            "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
            "places": [
                { "key": "client_signature", "type": "signature", "recipient_key": "client" }
            ],
            "fixed_positions": [
                { "place_key": "client_signature", "page": 1, "top": 600, "left": 72 }
            ]
        }
    ]
}
Multiple methods
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
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",
                            "Logged In At": "2026-12-31T23:59:59Z"
                        }
                    },
                    {
                        "type": "email_code"
                    }
                ]
            }
        }
    ],
    "documents": [
        {
            "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
            "places": [
                { "key": "client_signature", "type": "signature", "recipient_key": "client" }
            ],
            "fixed_positions": [
                { "place_key": "client_signature", "page": 1, "top": 600, "left": 72 }
            ]
        }
    ]
}

Create Ceremony endpoint (manual)

Use the Create Ceremony endpoint after the envelope is created. This lets you change authentication methods or create new access for the same recipient.

Creating a new ceremony automatically revokes any previous ceremony for that recipient. Only the most recent ceremony remains active.

Common use cases:

  • Switch from custom authentication to email link if the recipient hasn’t signed within a set time.
  • Provide a new URL after the original one expires.
  • Update ceremony settings like the redirect URL.
Email Link
POST /v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/ceremonies HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
    "authentication": [
        {
            "type": "email_link"
        }
    ]
}
Email Code
POST /v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/ceremonies HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
    "authentication": [
        {
            "type": "email_code"
        }
    ]
}
Custom
POST /v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/ceremonies HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
    "authentication": [
        {
            "type": "custom",
            "provider": "SuperApp",
            "data": {
                "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
                "Logged In At": "2026-12-31T23:59:59Z"
            }
        }
    ]
}
Multiple
POST /v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/ceremonies HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
    "authentication": [
        {
            "type": "custom",
            "provider": "SuperApp",
            "data": {
                "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
                "Logged In At": "2026-12-31T23:59:59Z"
            }
        },
        {
            "type": "email_code"
        }
    ]
}