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

# Custom Authentication

> Use your own authentication system to verify recipients before they access the signing ceremony.

With custom authentication, your application or workflow authenticates the [recipient](/docs/api/resources/recipients/object). SignatureAPI provides a ceremony URL that you share directly with the recipient to start their signing session.

## When to use

Custom authentication is the right choice when:

* Recipients are already authenticated in your system.
* You want to integrate signing into your existing application flow.
* You need specific authentication methods (biometrics, SSO, multi-factor).
* You want to embed the ceremony in your application.

After creating the ceremony, you can:

* Send the URL via email or SMS with your own branding.
* Redirect the recipient directly to the ceremony.
* Embed the ceremony in your application interface.
* Include the URL in push notifications.

## Creating a custom authentication ceremony

### On envelope creation (automatic)

Set the recipient's ceremony authentication to `custom` when creating the envelope. Include your authentication details in the `provider` and `data` properties.

```json Custom authentication ceremony on envelope creation 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",
                            "Authenticated At": "2025-12-31T23:59:59Z"
                        }
                    }
                ]
            }
        }
    ],
    "documents": [ /* ... */ ]
}
```

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

```json Response (excerpt) theme={null}
{
    "id": "abcdef12-3456-7890-1234-abcdef123456",
    "title": "Service Agreement",
    "recipients": [
        {
            "type": "signer",
            "key": "client",
            "ceremony": {
                "authentication": [
                    {
                        "type": "custom",
                        "provider": "SuperApp",
                        "data": {
                            "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
                            "Authenticated At": "2025-12-31T23:59:59Z"
                        }
                    }
                ],
                "url": "https://sign.signatureapi.com/en/start?token=eyJhbGcNiIsInR..."
            }
        }
    ]
}
```

### Create Ceremony endpoint (manual)

Use the [Create Ceremony](/docs/api/resources/ceremonies/create) endpoint to create a custom authentication 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.
</Note>

```json Create custom authentication ceremony 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",
        "Authenticated At": "2025-12-31T23:59:59Z"
      }
    }
  ]
}
```

The `url` property in the response is the ceremony URL to deliver to the recipient.

```json Response theme={null}
// HTTP Status Code 201

{
  "authentication": [
    {
      "type": "custom",
      "provider": "SuperApp",
      "data": {
        "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
        "Authenticated At": "2025-12-31T23:59:59Z"
      }
    }
  ],
  "embeddable_in": [],
  "redirect_url": null,
  "redirect_delay": 3,
  "url_variant": "standard",
  "url": "https://sign.signatureapi.com/en/start?token=eyJhbGcNiIsInR..."
}
```

## Authentication provider

Set `provider` to the name of the company or application that authenticated the recipient. This value appears in the audit log:

> John Doe has been authenticated by \[Provider Name]

## Authentication data

The `data` property holds key-value pairs that link the ceremony to your authentication records. These values appear in the envelope audit log.

<Note>
  The values in `data` must be sufficient to verify how the recipient was authenticated. In edge cases such as legal proceedings, you may need to provide your internal records to confirm the recipient's identity.

  When using custom authentication, retain all records necessary to prove authentication. Review our [Terms & Conditions](https://signatureapi.com/terms) for details.
</Note>

Useful data to include:

* **Session data:** Session IDs and session start timestamps that link to your authentication records.
* **User identification:** Email addresses, phone numbers, or user IDs from your system.
* **Authentication method:** The method used (OTP, biometrics, SSO) and relevant details like device IDs or IP addresses.
* **Transaction references:** Hashes, nonces, or other unique identifiers.

Example with rich authentication data:

```json theme={null}
{
  "type": "custom",
  "provider": "SuperApp",
  "data": {
    "Session ID": "a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3",
    "Order Reference": "25005",
    "Authentication Timestamp": "2025-12-31T10:00:00Z",
    "Authentication Method": "SMS",
    "Phone Number": "+1-111-1111111",
    "IP Address": "100.100.100.100"
  }
}
```

<Warning>
  Review the values in `data` carefully. Do not include unnecessary sensitive information.
</Warning>

## Using the ceremony URL

After creating the ceremony, you receive the URL. You can:

* Send a customized email using your own domain and branding.
* Embed the ceremony in your application.
* Redirect the recipient from your application directly to the ceremony.

<Warning>
  Treat ceremony URLs as sensitive credentials. Do not expose them in public forums or share them with unauthorized users.
</Warning>

## Audit log

When a recipient accesses a ceremony using custom authentication, SignatureAPI records the timestamp, provider, and authentication data. The audit log entry looks like this:

<div class="text-sm text-gray-500 border border-gray-200 rounded-md p-4 flex gap-8">
  <div class="flex-none">12/31/2025 11:59:59 PM</div>

  <div class="flex-1">
    <div>John Doe (#7161cf07) has been authenticated by SuperApp:</div>

    <div className="border-l border-gray-500 pl-2 my-1">
      <div>Session ID: a4f9e8b2-7c1d-4b2d-9a4b-e0c5d6f7a1b3</div>
      <div>Order Reference: 25005</div>
      <div>Authenticated At: Dec 31, 2025 23:59:59</div>
      <div>Authentication Method: SMS</div>
      <div>Phone Number: +1-111-1111111</div>
      <div>IP Address: 100.100.100.100</div>
    </div>

    <div>As provided by the initiator of the electronic signature transaction.</div>
  </div>
</div>