---
title: "Recipient Authentication"
description: "Choose how recipients verify their identity before accessing a signing ceremony."
canonical: "https://signatureapi.com/docs/api/resources/ceremonies/authentication/overview"
source: "https://signatureapi.com/docs/api/resources/ceremonies/authentication/overview.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T12:10:02Z"
---

# Recipient Authentication

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

_Last verified against API version 1.18.0._

Before a recipient can access a [ceremony](https://signatureapi.com/docs/api/resources/ceremonies/object), 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?**

- 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)**
      - Yes, add a second step: **Email link, then email code**
  - 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**
          - Yes, add an email code: **Custom, then email code**
      - No, SignatureAPI should check their email: **Email code**

**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](https://signatureapi.com/docs/api/resources/ceremonies/authentication/email-link).

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

**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](https://signatureapi.com/docs/api/resources/ceremonies/authentication/multiple), [HIPAA](https://signatureapi.com/docs/trust/compliance/hipaa).

```json
"ceremony": {
  "authentication": [
    { "type": "email_link" },
    { "type": "email_code" }
  ]
}
```

**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](https://signatureapi.com/docs/api/resources/ceremonies/authentication/email-code), [Ceremony URL](https://signatureapi.com/docs/api/resources/ceremonies/ceremony-url).

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

**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](https://signatureapi.com/docs/api/resources/ceremonies/authentication/custom).

```json
"ceremony": {
  "authentication": [
    {
      "type": "custom",
      "provider": "Your App",
      "data": { "session_id": "..." }
    }
  ]
}
```

**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](https://signatureapi.com/docs/api/resources/ceremonies/authentication/multiple).

```json
"ceremony": {
  "authentication": [
    { "type": "custom", "provider": "Your App", "data": { "session_id": "..." } },
    { "type": "email_code" }
  ]
}
```

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

**Email link**

Participants: Your app, SignatureAPI, Recipient.

1. **Your app** to **SignatureAPI**: Create the envelope (default ceremony)
2. **SignatureAPI** to **Recipient**: Invitation email with the link
3. **Recipient** to **SignatureAPI**: Open the link
   Opening the link authenticates the recipient. The ceremony `url` is `null` in API responses.

[Learn more about Email Link Authentication](https://signatureapi.com/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.

- 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**

Participants: 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
   Use your own email, SMS or in-app link.
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

[Learn more about Email Code Authentication](https://signatureapi.com/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.

**Custom**

Participants: Your app, SignatureAPI, Recipient.

1. **Your app** to **Recipient**: Authenticate the recipient
   Sign-in, SSO or any method you use.
2. **Your app** to **SignatureAPI**: Create the ceremony with `custom`
   Send `provider` and `data` for the audit log.
3. **SignatureAPI** to **Your app**: Ceremony `url`
4. **Your app** to **Recipient**: Deliver or embed the URL

[Learn more about Custom Authentication](https://signatureapi.com/docs/api/resources/ceremonies/authentication/custom)

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

Participants: 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
   The first method decides delivery, so `url` stays `null` and your app sends nothing.
3. **Recipient** to **SignatureAPI**: Open the link
4. **SignatureAPI** to **Recipient**: Email with the 9-digit code
5. **Recipient** to **SignatureAPI**: Enter the code

[Learn more about Multiple Authentication Methods](https://signatureapi.com/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.

#### Email Link (default)

```http
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

```http
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

```http
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

```http
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](https://signatureapi.com/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.

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

```http
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

```http
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

```http
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

```http
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"
        }
    ]
}
```
