Skip to main content
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.
If scoped API keys or built-in tenant isolation would be valuable for your use case, let us know at support@signatureapi.com. We are evaluating this feature based on demand.

​
Use metadata to identify tenants

Attach your tenant identifier to each envelope using metadata. This lets you correlate envelopes with tenants in webhook handlers and when listing envelopes. 
// 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: 
{
    "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 to tag envelopes and configure separate webhook endpoints for each topic. 
{
    "title": "Service Agreement",
    "topics": ["tenant_abc123"],
    "metadata": {
        "tenant_id": "tenant_abc123"
    },
    //...
}

​
Per-tenant branding

Customize the signing experience for each tenant using the branding property on each envelope. Set a different logo, accent color, and email footer per tenant. 
{
    "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 email address. Create and verify a sender for each tenant, then specify it on the envelope. 
{
    "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 to link envelopes to your internal records.
  • Use topics to filter webhooks by tenant or category.
  • Customize the signing experience with branding.
  • Manage senders for per-tenant Reply-To addresses.