---
title: "Email Code Authentication"
description: "Authenticate recipients with a verification code sent to their email address."
canonical: "https://signatureapi.com/docs/api/resources/ceremonies/authentication/email-code"
source: "https://signatureapi.com/docs/api/resources/ceremonies/authentication/email-code.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T12:10:02Z"
---

# Email Code Authentication

Authenticate recipients with a verification code sent to their email address.

_Last verified against API version 1.18.0._

With email code authentication, SignatureAPI sends the [recipient](https://signatureapi.com/docs/api/resources/recipients/object) an email containing a 9-digit verification code. The recipient enters this code to authenticate and access their signing ceremony.

## When to use

Email code authentication is useful when:

- You want to share the ceremony URL through your own channels (SMS, app notifications, direct links).
- Recipients are in environments where email links may be blocked by security policies.
- You want to embed the ceremony in your application while still using email-based authentication.
- You want SignatureAPI to email the invitation as usual, with a verification code as a second step.

## Who delivers the ceremony URL

`authentication` is an ordered array, and its **first** method decides who delivers the ceremony URL. Email code behaves differently depending on where you place it:

| `authentication`           | Invitation email           | `url` in the response |
| -------------------------- | -------------------------- | --------------------- |
| `[email_code]`             | None. You deliver the URL. | Returned              |
| `[email_link, email_code]` | Sent by SignatureAPI       | `null`                |
| `[custom, email_code]`     | None. You deliver the URL. | Returned              |

Placing `email_code` after `email_link` keeps SignatureAPI responsible for both emails, the invitation link and the code, so your application sends neither. See [Multiple Authentication Methods](https://signatureapi.com/docs/api/resources/ceremonies/authentication/multiple) for that combination.

The rest of this page describes `email_code` as the **first** method, where you deliver the URL yourself.

## How it works

1. **Configure the ceremony**

   Create an envelope or call the Create Ceremony endpoint with `email_code` as the first authentication method. The API returns the ceremony URL.

2. **Deliver the URL**

   Share the ceremony URL with the recipient through your chosen channel (email, SMS, in-app link, etc.).

3. **Recipient enters code**

   When the recipient opens the URL, SignatureAPI prompts them to verify their email. After they click the verification button, SignatureAPI sends them a 9-digit code by email.

4. **Authentication complete**

   The recipient enters the code. Once verified, they can proceed with signing.

## Creating an email code ceremony

### On envelope creation (automatic)

Set the recipient's ceremony authentication to `email_code` when creating the envelope. Because it is the first method, the ceremony URL is returned in the response.

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

The response includes `ceremony.url` for each recipient:

```json Response (excerpt)
{
    "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
    "title": "Service Agreement",
    "recipients": [
        {
            "type": "signer",
            "key": "client",
            "name": "John Doe",
            "email": "john.doe@example.com",
            "ceremony": {
                "authentication": [
                    {
                        "type": "email_code"
                    }
                ],
                "url": "https://sign.signatureapi.com/en/start?token=eyJhbGcNiIsInR..."
            }
        }
    ]
}
```

### Create Ceremony endpoint (manual)

Use the [Create Ceremony](https://signatureapi.com/docs/api/resources/ceremonies/create) endpoint to create an email code ceremony after the envelope is created.

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

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

The `url` property in the response is the ceremony URL to deliver to the recipient. It is `null` instead when `email_link` is the first method.

```json 201 Created
{
  "authentication": [
    {
      "type": "email_code"
    }
  ],
  "embeddable_in": [],
  "redirect_url": null,
  "redirect_delay": 3,
  "url_variant": "standard",
  "url": "https://sign.signatureapi.com/en/start?token=eyJhbGcNiIsInR..."
}
```

## Recipient experience

1. **Email verification prompt**

   The recipient opens the ceremony URL and sees their masked email address with a **Send code** button.

   ![Ceremony prompt asking the recipient to confirm their masked email address, with a Send code button](https://signatureapi.com/docs/images/ceremony-email-code-send.webp)

   *Ceremony, email verification prompt*

2. **Code sent by email**

   After the recipient clicks **Send code**, SignatureAPI sends them an email with the 9-digit code.

   ![Verification code email showing a 9-digit code and a warning not to share it](https://signatureapi.com/docs/api/resources/ceremonies/authentication/email-code/email-code-2.webp)

   > **Tip:** In test mode, no emails are sent. You can view the verification codes that would have been sent in the SignatureAPI dashboard under ceremony details.

3. **Code entry**

   The recipient enters the code in the ceremony. The page shows the first digits of the code to help them find the right email, and a **Resend code** button with a countdown.

   ![Ceremony code entry with nine digit boxes, the first three filled, a Show document button, a Reset button and a Resend code button with a countdown](https://signatureapi.com/docs/images/ceremony-email-code-enter.webp)

   *Ceremony, code entry*

4. **Access granted**

   After the correct code is entered, the recipient can proceed with signing.

   ![Ceremony showing the document with a Start button after the code is accepted](https://signatureapi.com/docs/api/resources/ceremonies/authentication/email-code/email-code-5.webp)

## Code validity, attempts and resending

The ceremony enforces these rules for each code:

- **Format:** the code has 9 digits.
- **Validity:** a code is valid for 1 hour after it is issued. Asking for a code again within that hour sends the same code. After it expires, the next request issues a new one.
- **Wrong entries:** a code accepts up to 5 incorrect entries. After the fifth, it is locked until it expires, and the recipient gets a "Too many invalid code attempts" error.
- **Resending:** the recipient resends the code from the ceremony. The first wait is 30 seconds and it doubles with each send of the same code (30, 60, 120 seconds, and so on). A request during the wait doesn't send another email.

Your application can't send or resend the code through the API. If the recipient is locked out or can't find the email, they wait out the countdown or the hour, or you create a new ceremony for them and give them the new URL.

## Audit log

When the recipient enters the verification code, SignatureAPI records the timestamp. The audit log entry looks like this:

12/31/2025 11:59:59 PM John Doe (#7161cf07) has authenticated using a verification code sent to john⁠@example.com.
