You can combine multiple authentication methods in a ceremony to create layered authentication workflows. This provides flexibility in how recipients access and authenticate for signing ceremonies.

​
Authentication Order Rules

SignatureAPI enforces specific rules for combining authentication methods: The table below shows which authentication methods you can use as the first step or as a secondary (or later) step in a ceremony. Use this as a quick reference when designing your authentication workflow.
Authentication MethodFirst Step AllowedSecond Step and Up Allowed
Email Link Authentication✅❌
Email Code Authentication✅✅
Custom Authentication✅❌
  • First Step Allowed: You can use this method as the initial authentication step.
  • Second Step and Up Allowed: You can use this method after another authentication method (as a secondary or later step).

​
Common Combinations

​
Custom + Email Code

Combine custom authentication with email code for enhanced verification. Use case: When you want to authenticate the signer in your own application, and also require SignatureAPI to independently verify the signer’s identity (by sending a verification code to their email). 
// 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": "sess_12345",
                "authenticated_at": "2024-01-15T10:30:00Z",
                "user_id": "user_67890"
            }
        },
        {
            "type": "email_code"
        }
    ]
}

​
Recipient Experience

1

Your Application

The recipient authenticates in your system (custom authentication)
2

Ceremony Access

You direct them to the ceremony URL or embed the ceremony UI in your app
3

Email Verification

SignatureAPI prompts for additional email verification.
4

Code Entry

Recipient enters the 9-digit code from their email
5

Signing

Recipient proceeds to sign documents
Combine email link with email code for enhanced email-based verification. Use case: When you want SignatureAPI to send the signature request email automatically, but also need to authenticate the recipient’s access inside the ceremony for compliance reasons (e.g., HIPAA requirements). 
// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies
// X-API-Key: key_test_...
// Content-Type: application/json

{
    "authentication": [
        {
            "type": "email_link"
        },
        {
            "type": "email_code"
        }
    ]
}

​
Recipient Experience

1

Email Link

Recipient clicks the ceremony link in the email sent by SignatureAPI
2

Email Verification

SignatureAPI prompts for additional email verification for compliance
3

Code Entry

Recipient enters the 9-digit verification code from their email
4

Signing

Recipient proceeds to sign documents

​
Best Practices

  1. Match Your Use Case: Choose authentication combinations that align with your security requirements and user experience goals
  2. Consider User Experience: More authentication steps provide stronger verification but may impact user convenience
  3. Test Combinations: Always test the complete authentication flow in test mode before production

​
Limitations

  • Custom and email link authentication can only be used as the first method
  • Custom and email link authentication cannot be combined together
  • Cannot use duplicate authentication methods in the same ceremony
  • All authentication methods must be completed in sequence
  • Combined authentication requires manual ceremony creation (cannot be used with automatic ceremony creation)

​
Next Steps