Managing Your API Keys

Overview

When building with Verdocs, it helps to understand the difference between four related concepts:

• User: A person with a Verdocs identity.
• Organization: A company, workspace, tenant, or customer account in Verdocs.
• Profile: A user’s relationship to a specific organization.
• Recipient: A person who receives or signs an envelope.

In most server-side integrations, your application authenticates with an API key that acts as a specific profile inside a specific organization. This lets your backend create templates, send envelopes, retrieve completed documents, and manage signing workflows without asking an end user to log in to Verdocs.

Are API keys tied to users, organizations, or applications?

API keys are created under a Verdocs profile, and that profile belongs to an organization. In practice, this means an API key acts as a specific user/profile within a specific organization.

For production integrations, we recommend creating a dedicated API user or service profile instead of using a personal developer account. This keeps your integration separate from an employee’s personal login and avoids unexpected behavior if that person belongs to multiple organizations or switches their current profile.

Recommended pattern:

Your SaaS application → Verdocs API key → API user / service profile → Verdocs organization

Should I use one API key or one API key per organization?

For a single organization, one API key is often enough.

For a multi-tenant SaaS platform, the recommended pattern is usually:

Parent Verdocs organization → Child organization / sub-account for Customer A → API key for Customer A workflows

→ Child organization / sub-account for Customer B → API key for Customer B workflows

This keeps templates, envelopes, branding, permissions, and usage cleanly separated by customer.

If you create child organizations using the API, the parent organization can establish the parent-child relationship. After that, operations inside the child organization should use credentials/API keys associated with that child organization. The parent token is used to create the relationship, not to perform all future operations inside every sub-account. Your existing organization hierarchy guide already states this, but it should be repeated in this new guide because it directly answers Steve’s question.

Is there a master API key that can act as any organization?

Generally, no. Verdocs should not be presented as a single global “master key” model where one credential freely impersonates every organization.

The safer mental model is: One API key acts as one profile in one organization.

For embedded SaaS platforms, use organization hierarchies to manage parent/child relationships, entitlements, and usage reporting, while using organization-specific credentials for the actual work inside each customer account. The docs already explain that sub-accounts can inherit entitlements and that usage metrics can be retrieved for monitoring and billing.

Do my signers need Verdocs member accounts?

No. A person who signs an envelope does not need to be a member of your Verdocs organization.

In Verdocs, organization members are people who administer, create, send, or manage workflows inside an organization. Recipients/signers are simply participants in an envelope. When your application creates an envelope, it supplies the recipient information such as name, email, role, and signing order.

Example:

const request = {
  template_id,
  name: 'Customer Agreement',
  roles: [
    { type: 'signer', name: 'Customer', email: 'customer@example.com', sequence: 1 },
    { type: 'signer', name: 'Manager', email: 'manager@example.com', sequence: 2 },
  ],
};

Your current server workflow guide already shows this model: recipients/roles are provided when creating the envelope, and the returned envelope can be used later to retrieve status or final signed documents.

Can my app send or sign “on behalf of” users?

Your server can create and send envelopes using its API key. The recipient does not need to authenticate into Verdocs as a member of your organization.

You have two common options:

1. **Verdocs-managed notification flow → **Verdocs sends the email or SMS invitation to the recipient.
2. **Application-managed notification flow → **Your application handles the email, SMS, or in-app notification. In this case, create the envelope with no_contact: true, then retrieve signing links for the recipients and deliver them through your own app experience.

Your server workflow guide already explains this no_contact pattern and shows retrieving signing links for recipients.