---
title: "Custom Authentication"
description: "Use your own authentication system to verify recipients before they access the signing ceremony."
canonical: "https://signatureapi.com/docs/api/resources/ceremonies/authentication/custom"
source: "https://signatureapi.com/docs/api/resources/ceremonies/authentication/custom.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T12:10:02Z"
---

# Custom Authentication

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

_Last verified against API version 1.18.0._

With custom authentication, your application or workflow authenticates the [recipient](https://signatureapi.com/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.

```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",
                            "Authenticated At": "2025-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 }
            ]
        }
    ]
}
```

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

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

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

```json 201 Created
{
  "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/docs/legal/terms/terms) for details.

Rules for `provider` and `data`:

- `provider` is a required, non-empty string.
- `data` is a required object with at least one key.
- Every value in `data` must be a string. Send numbers, booleans and timestamps as strings.

A request that breaks a rule returns a `422` with the broken rule in `errors`, for example `authentication[0].data must not be empty.` or `authentication[0].data.Order Reference must be a string.` See [Validation Error](https://signatureapi.com/docs/v1/errors/validation-error).

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
{
  "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.

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

## Audit log

When a recipient accesses a ceremony using custom authentication, SignatureAPI records the timestamp, provider, and authentication data. The audit log lists each `data` key and value as you sent them, in the same order. For the rich example above, the entry looks like this:

12/31/2025 11:59:59 PM

John Doe (#7161cf07) has been authenticated by SuperApp:

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

As provided by the initiator of the electronic signature transaction.
