API Docs

AI Toolkit

Pricing

$0.25

API Docs

AI Toolkit

Changelog

Pricing

$0.25

All posts
Guides

Building a multi-tenant e-signature feature for your SaaS customers

How to offer document signing to every customer of your SaaS platform from one SignatureAPI account, with tenant routing, per-tenant branding and senders, and clean data boundaries.

Platforms add signing in two stages. First the platform itself needs a signature, usually on its own customer agreement. Later its customers ask for signing inside the product: a property manager wants tenants to sign leases, a staffing agency wants contractors to sign onboarding forms, an agency wants clients to sign statements of work. The second stage is a multi-tenant feature, and it raises questions the first one didn’t.

This post describes how to build that feature on SignatureAPI. It covers where tenancy lives, how events find the right tenant, how each tenant’s signers see that tenant’s brand, and the checks that keep one tenant’s documents away from another.

Where tenancy lives

SignatureAPI does not provide scoped API keys, separate projects or tenant isolation at the API level. Your platform uses one SignatureAPI account and one API key, and your application decides which tenant owns each envelope.

That sounds like a limitation, and in one sense it is. It also matches how a platform already handles the rest of its data. Your tenants don’t have SignatureAPI accounts and never see SignatureAPI credentials. They use your product, your product calls the API on their behalf, and your authorization rules decide who can see what. You don’t have to provision anything per tenant, and onboarding a new tenant is a row in your own database.

It also means the boundary is your responsibility. Every request your backend makes must be checked against the tenant of the user who triggered it, the same way you check access to any other record.

Tag every envelope with its tenant

Attach the tenant identifier to each envelope with metadata. An envelope can carry up to 10 key-value pairs, and the metadata comes back in every API response for that envelope and in every webhook payload as envelope_metadata.

JSON
{
  "title": "Lease Agreement",
  "metadata": {
    "tenant_id": "tnt_8f2c",
    "contract_id": "lease_4471"
  },
  "documents": [ //... ],
  "recipients": [ //... ]
}

Store the envelope’s id next to your own record as well. Your database is the source of truth for ownership. Metadata is a convenience for routing, and you should not put sensitive data in it.

Route events to the right tenant

Register one webhook endpoint for the platform. When an event arrives, verify its signature, read data.envelope_metadata.tenant_id, and hand the event to that tenant’s logic. Deliveries can arrive out of order and are retried for up to 48 hours, so make each handler safe to run twice.

If some tenants need different handling, such as a separate integration, use topics. You can tag an envelope with up to 10 topics and configure a webhook endpoint to receive only envelopes with certain topics. Topic filters on webhook endpoints are enabled on request through support. Topics also work as a filter when you list envelopes.

Give each tenant its own look

Signers should see your tenant’s name and brand, not yours and certainly not ours. Two envelope properties do most of the work.

Branding sets a logo, an accent color and an email footer per envelope. It applies to the signing ceremony and to the emails recipients receive, at no extra cost. Look up the tenant’s settings when you build the envelope and pass them along.

The sender sets the name, email address and organization that appear in signing emails, and the address becomes the Reply-To. A signer who replies with a question reaches the tenant, not your support queue. Each sender address must be verified by its owner before you can use it. You can manage senders in the Dashboard, and sender management through the API is in public preview on request.

SignatureAPI branding, such as the “Powered by SignatureAPI” credit, still appears next to your tenant’s brand. If your platform needs to remove it or send from your own domain, the branding add-ons are paid options that apply to the whole account.

Keep signing inside your product

When the signer is one of your tenant’s own users, logged into your product, embed the ceremony instead of sending an email. Create the recipient with custom authentication and your own user reference, set ceremony.embeddable_in to your app’s origin, and set delivery_type to none if your app distributes the signed PDF itself. The response includes a ceremony URL that you load in an iframe or a mobile WebView. Your authentication details are recorded in the audit log.

When the signer is outside your product, such as a tenant’s client or a contractor, keep the default email link. SignatureAPI sends the invitation using the tenant’s sender and branding.

Store deliverables in the tenant’s space

When an envelope completes, SignatureAPI generates the deliverable: the signed documents and an audit log, sealed so that anyone can verify the file has not changed. The deliverable.generated event carries a download link that expires after one hour.

Download the file right away and store it where the tenant’s other data lives, such as a per-tenant bucket or prefix. Then your platform’s retention, export and deletion rules apply to signed documents the same way they apply to everything else.

Checks that keep tenants apart

A short list catches most mistakes:

  • Every endpoint that takes an envelope ID loads your own record first and checks that it belongs to the caller’s tenant. Never trust an envelope ID from the client on its own.
  • Webhook handlers route on metadata, then confirm the envelope exists in your database under that tenant.
  • Ceremony URLs and deliverable links go only to the user they were created for. They grant access without an API key.
  • Test and live mode stay separate end to end. Test envelopes, webhooks and senders are independent from live ones, and a test key never reaches live envelopes.

Billing per tenant

SignatureAPI bills one account for completed envelopes, so you decide how to charge your tenants. The envelope metadata and your own records give you a per-tenant count of completed envelopes from the envelope.completed events your platform already receives.

The multi-tenant guide has the request examples for each step. If scoped API keys or built-in tenant isolation would change your design, tell us at support@signatureapi.com. We are evaluating that feature based on demand.

START FOR FREE

Ready to get started?
Create an account instantly, no credit card required.

Get Started