A ceremony is the session where a recipient interacts with an envelope to complete actions like signing documents. Before accessing a ceremony, recipients must authenticate their identity. SignatureAPI offers multiple authentication methods that can be used individually or combined to meet your security and user experience requirements.

​
Authentication Methods

SignatureAPI sends recipients an email containing a direct link to the ceremony. When recipients click the link, they’re automatically authenticated and can proceed with signing.
  • Default method: Automatically used when you create envelopes
  • Zero setup: Works out of the box with no configuration needed
  • Simple experience: One-click access for recipients
  • Automatic ceremony creation: Ceremonies are created and emails sent automatically
Learn more about Email Link Authentication →

​
Email Code Authentication

SignatureAPI sends recipients an email containing a 9-digit verification code. Recipients must enter this code in the ceremony interface to authenticate.
  • URL control: You receive the ceremony URL to share via your own channels
  • Email verification: Ensures recipients have access to their email account
  • Flexible sharing: Send the ceremony URL via SMS, app notifications, or direct links
  • Manual ceremony creation: Requires manual ceremony setup
Learn more about Email Code Authentication →

​
Custom Authentication

Your application authenticates recipients using your own methods. SignatureAPI provides a ceremony URL that you can share directly or embed in your application.
  • Full control: Authenticate recipients using your existing systems
  • Embedding support: Perfect for in-app signing experiences
  • Custom audit trail: Your authentication details are included in the audit log
  • Maximum flexibility: Use any authentication method your application supports
Learn more about Custom Authentication →

​
Automatic vs Manual Ceremony Creation

​
Automatic Creation (Default)

By default, SignatureAPI automatically creates ceremonies and sends authentication emails when you create an envelope. This works only with email link authentication. 
// 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_creation defaults to "automatic"
        }
    ]
    //...
}
When to use automatic creation:
  • Simple signing workflows
  • You want SignatureAPI to handle email delivery
  • Standard email link authentication meets your needs

​
Manual Creation

For more control, set ceremony_creation to manual when creating envelopes. This prevents automatic ceremony creation and allows you to use any authentication method. 
// 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_creation": "manual"
        }
    ]
    //...
}
Then create the ceremony using your preferred authentication method: 
// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies
// X-API-Key: key_test_...
// Content-Type: application/json

{
    "authentication": [
        {
            "type": "email_code"
        }
    ]
}
When to use manual creation:
  • You need custom or email code authentication
  • You want to control when ceremonies are created
  • You need to embed ceremonies in your application
  • You want to use multiple authentication methods

​
Multiple Authentication Methods

You can combine authentication methods for enhanced security or compliance requirements. Each method must be completed in sequence before recipients can access the ceremony. Learn more about Multiple Authentication Methods →

​
Choosing the Right Method

  • You want the simplest setup and user experience
  • Recipients expect to receive signing requests via email
  • You don’t need to control the ceremony URL
  • Standard authentication meets your security requirements

​
Use Email Code When:

  • You want to control how recipients access the ceremony URL
  • You need to embed ceremonies in your application
  • You want email-based authentication with URL flexibility
  • Recipients are in environments where email links might be blocked

​
Use Custom When:

  • You want to authenticate recipients using your own systems
  • You need to embed ceremonies seamlessly in your application
  • You want complete control over the authentication process
  • You have specific authentication requirements (SSO, 2FA, etc.)

​
Use Multiple Methods When:

  • Compliance regulations require layered authentication (e.g., HIPAA)
  • You need both application-level and email-level verification
  • Enhanced security is required for high-value transactions

​
Security and Audit Trail

All authentication methods create detailed audit log entries that include:
  • Authentication method used
  • Timestamp of authentication
  • IP address and user agent
  • Authentication provider (for custom authentication)
  • Success or failure status

​
Example Audit Log Entry

Custom Authentication: John Doe authenticated via YourApp at 2024-01-15 10:30:22 UTC (IP: 192.168.1.100) Email Code Authentication: Verification code sent to john.doe@example.com at 2024-01-15 10:31:15 UTC Email Code Verified: John Doe successfully authenticated with verification code at 2024-01-15 10:32:08 UTC
This comprehensive audit trail ensures compliance with legal and regulatory requirements.

​
URL Security and Expiration

All ceremony URLs are:
  • Unique and unpredictable: Generated with cryptographically secure tokens
  • Time-limited: Expire after 30 days for security
  • Single-use context: Tied to specific recipient and envelope
URLs are automatically revoked when:
  • The recipient completes the ceremony
  • You create a new ceremony for the same recipient
  • The envelope is canceled or completed by all recipients
Treat ceremony URLs as sensitive data. Do not share them in public forums, logs, or with unauthorized users. Each URL provides direct access to the signing ceremony for the associated recipient.

​
Best Practices

  1. Start Simple: Begin with email link authentication for basic use cases
  2. Test Thoroughly: Always test authentication flows in test mode before production
  3. Consider User Experience: Balance security requirements with ease of use
  4. Plan for Failures: Implement fallback processes for authentication issues
  5. Secure URL Handling: Treat ceremony URLs as sensitive, time-sensitive credentials
  6. Monitor Audit Logs: Regularly review authentication events for security monitoring

​
Next Steps