> ## Documentation Index
> Fetch the complete documentation index at: https://signatureapi-daf4ee54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipient Authentication

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

Before a recipient can access a [ceremony](/docs/api/resources/ceremonies/object), they must authenticate. SignatureAPI supports three authentication methods that you can use individually or combine for added security.

## Authentication methods

### Email Link (default)

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](/docs/api/resources/ceremonies/authentication/email-link)

### Email Code

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

* You receive the ceremony URL to share through your own channels.
* Confirms the recipient has access to their email account.
* Supports SMS, app notifications, or direct links as delivery channels.

[Learn more about Email Code Authentication](/docs/api/resources/ceremonies/authentication/email-code)

### 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.

[Learn more about Custom Authentication](/docs/api/resources/ceremonies/authentication/custom)

### Multiple methods

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

[Learn more about Multiple Authentication Methods](/docs/api/resources/ceremonies/authentication/multiple)

## 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.

<CodeGroup>
  ```json Email Link (Default) theme={null}
  // 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"
          }
      ],
      "documents": [ /* ... */ ]
  }
  ```

  ```json Email Code theme={null}
  // 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": "email_code"
                      }
                  ]
              }
          }
      ],
      "documents": [ /* ... */ ]
  }
  ```

  ```json Custom theme={null}
  // 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",
                              "Logged In At": "2026-12-31T23:59:59Z"
                          }
                      }
                  ]
              }
          }
      ],
      "documents": [ /* ... */ ]
  }
  ```

  ```json Multiple theme={null}
  // 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",
                              "Logged In At": "2026-12-31T23:59:59Z"
                          }
                      },
                      {
                          "type": "email_code"
                      }
                  ]
              }
          }
      ],
      "documents": [ /* ... */ ]
  }
  ```
</CodeGroup>

### Create Ceremony endpoint (manual)

Use the [Create Ceremony](/docs/api/resources/ceremonies/create) endpoint after the envelope is created. This lets you change authentication methods or create new access for the same recipient.

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

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.

<CodeGroup>
  ```json Email Link theme={null}
  // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies
  // X-API-Key: key_test_...
  // Content-Type: application/json

  {
      "authentication": [
          {
              "type": "email_link"
          }
      ]
  }
  ```

  ```json Email Code theme={null}
  // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/ceremonies
  // X-API-Key: key_test_...
  // Content-Type: application/json

  {
      "authentication": [
          {
              "type": "email_code"
          }
      ]
  }
  ```

  ```json Custom theme={null}
  // 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",
                  "Logged In At": "2026-12-31T23:59:59Z"
              }
          }
      ]
  }
  ```

  ```json Multiple theme={null}
  // 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",
                  "Logged In At": "2026-12-31T23:59:59Z"
              }
          },
          {
              "type": "email_code"
          }
      ]
  }
  ```
</CodeGroup>