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

# Multi-Tenant Applications

> Integrate SignatureAPI into a multi-tenant SaaS platform where each tenant has its own signing workflows

If you are building a SaaS platform where multiple tenants (customers, organizations, or accounts) need to send documents for signature, this guide explains how to structure your integration with SignatureAPI.

## How tenancy works

SignatureAPI does not provide scoped API keys, separate projects, or tenant isolation at the API level. Your application uses a single API key and manages tenancy on your side.

This means:

* **One SignatureAPI account** serves all your tenants.
* **Your application** decides which tenant each envelope belongs to.
* **Your application** controls which tenants can see which envelopes and deliverables.
* **Your end users do not need SignatureAPI accounts.** They interact with your application, which calls the SignatureAPI on their behalf.

<Note>If scoped API keys or built-in tenant isolation would be valuable for your use case, let us know at [support@signatureapi.com](mailto:support@signatureapi.com). We are evaluating this feature based on demand.</Note>

## Use metadata to identify tenants

Attach your tenant identifier to each envelope using [metadata](/docs/api/resources/envelopes/metadata). This lets you correlate envelopes with tenants in webhook handlers and when listing envelopes.

```json theme={null}
// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_live_...
// Content-Type: application/json

{
    "title": "Service Agreement",
    "metadata": {
        "tenant_id": "tenant_abc123",
        "tenant_name": "Acme Corp"
    },
    "documents": [ //... ],
    "recipients": [ //... ]
}
```

When SignatureAPI sends webhook events, the `envelope_metadata` is included in every payload. Use it to route the event to the correct tenant in your system:

```json theme={null}
{
    "type": "recipient.completed",
    "data": {
        "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
        "envelope_metadata": {
            "tenant_id": "tenant_abc123",
            "tenant_name": "Acme Corp"
        },
        //...
    }
}
```

## Use topics to filter webhooks per tenant

If different tenants require different webhook handling, use [topics](/docs/api/resources/envelopes/topics) to tag envelopes and configure separate webhook endpoints for each topic.

```json theme={null}
{
    "title": "Service Agreement",
    "topics": ["tenant_abc123"],
    "metadata": {
        "tenant_id": "tenant_abc123"
    },
    //...
}
```

## Per-tenant branding

Customize the signing experience for each tenant using the [branding](/docs/api/resources/envelopes/branding) property on each envelope. Set a different logo, accent color, and email footer per tenant.

```json theme={null}
{
    "title": "Service Agreement",
    "branding": {
        "logo": "https://api.signatureapi.com/v1/uploads/upl_tenant_abc_logo",
        "accent_color": "#1a73e8",
        "email": {
            "footer": "Sent by Acme Corp via YourApp"
        }
    },
    //...
}
```

## Per-tenant senders

Each tenant can have their own [sender](/docs/api/resources/senders/object) email address. Create and verify a sender for each tenant, then specify it on the envelope.

```json theme={null}
{
    "title": "Service Agreement",
    "sender": {
        "name": "Acme Corp",
        "email": "signing@acmecorp.com",
        "organization": "Acme Corp"
    },
    //...
}
```

The sender's email appears as the Reply-To address in signing request emails.

## Architecture overview

A typical multi-tenant integration looks like this:

1. **Tenant creates a document** in your application.
2. **Your server** creates an envelope in SignatureAPI with the tenant's metadata, branding, and sender.
3. **SignatureAPI** handles the signing ceremony with the tenant's recipients.
4. **Webhook events** arrive at your server with the tenant metadata, so you can route them to the correct tenant.
5. **Your server** downloads the deliverable and stores it in the tenant's storage.

Your application is the control layer. SignatureAPI handles the signing infrastructure.

## Keep Learning

* Use [metadata](/docs/api/resources/envelopes/metadata) to link envelopes to your internal records.
* Use [topics](/docs/api/resources/envelopes/topics) to filter webhooks by tenant or category.
* Customize the signing experience with [branding](/docs/api/resources/envelopes/branding).
* Manage [senders](/docs/api/resources/senders/object) for per-tenant Reply-To addresses.