Skip to content
Docs
Documents & e-signature

DocuSign

Let hires send envelopes from your DocuSign templates for signature, after a person approves, follow who has signed, and be woken when an envelope is signed.

Explore 6 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With DocuSign connected, a hire can do exactly what it does with Documenso:

  • list your templates and the roles each one needs filled (like Client),
  • prepare an envelope from a template as a draft, for someone to check and send,
  • send an envelope from a template for signature, always after a person approves,
  • see an envelope's status and each signer's: waiting, viewed, signed or declined,
  • get a signed copy's reference: its file name, size and fingerprint, and where to download it.

Sending always asks first

Sending for signature commits your business, so send_for_signature always waits for an approval. The hire asks in the thread with the template, the title, every signer and the message; when the approver says yes, Roster sends exactly that, once. Drafts reach nobody and don't ask.

1. Make an app in DocuSign

DocuSign needs an app of yours before anything can connect:

  1. In DocuSign, open Settings → Apps and Keys and click Add App and Integration Key. Name it Roster and copy the integration key.
  2. Choose how Roster signs in:
    • JWT (recommended): Roster acts as one DocuSign user without anyone signing in again. Under the app, Generate RSA and keep the private key. Copy the User ID (a GUID) of the user hires should act as, ideally one named for your team, like Bayt Studio Contracts, since envelopes go out in that user's name. Add any redirect URI to the app (your website works), then open this address once in a browser, signed in as that user, and click Allow: https://account.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id=<integration key>&redirect_uri=<the redirect URI> (use account-d.docusign.com for a developer account).
    • Sign in with Connect: under the app, Add Secret Key and copy it, and add the callback address Roster shows on the connection as a redirect URI.
  3. DocuSign reviews an app before it works with production accounts ("go-live"). Until then, it works with a developer account.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for DocuSign and choose it.
  2. How Roster signs in: JWT or Sign in with Connect.
  3. DocuSign environment: Production, or Developer (demo) for a developer account.
  4. Integration key, and for JWT the User ID and the RSA private key (the whole key, from -----BEGIN to -----END); for Connect, the secret key, then click Connect.
  5. Account: only if the user has more than one DocuSign account.
  6. Business name: your business's name, like Bayt Studio.
  7. Documents hires may see: Only documents made through Roster (the default), or Every document this account can see. DocuSign accounts often hold contracts, offers and HR papers, so by default hires only see what they drafted or sent themselves.

3. Give hires access

On the hire's Tools tab, click Give access on DocuSign:

  • Read only: it can list templates, see envelopes' status and get signed copies' references.
  • Read and write: it can also draft envelopes and send them for signature (sending always asks a person first).
  • Templates: template names or IDs it may use. Leave it empty for every template.
  • Who it may send to: email domains (like client.example) or full addresses. Anyone else is refused, even with an approval.

Hires never get the signed PDF itself: they get its name, size and SHA-256 fingerprint, and the link where people signed in to DocuSign download it.

4. Get told when envelopes are signed (optional)

Without this, a hire watching DocuSign checks for finished envelopes now and then. To hear at once, with DocuSign Connect:

  1. In DocuSign, open Settings → Connect → Connect Keys and add a key; copy it.
  2. Under Connect → Configurations, add a custom configuration: this connection's webhook address (from its card in Roster) as the URL, JSON as the format, Include HMAC signature on, and at least Envelope completed, Envelope declined, Envelope voided and Recipient signed/completed.
  3. Paste the key in Connect HMAC key on the connection.

Roster checks every delivery's signature and ignores anything not signed with that key.

Saying it's an AI assistant

A hire never pretends to be a person. If you also want it to say so up front, turn on Say it's an AI assistant in first messages to outsiders under Settings → Workspace (more). Then the message in the first signing email to someone starts with "This is the AI assistant for" and your business name.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect DocuSign and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

Signed JWT bearer grant

The private key of the RSA key pair you added to the app in DocuSign, from -----BEGIN to -----END.

For: How Roster signs in: JWT (an app's RSA key, acting as one user).

Requested scopes:

  • signature
  • impersonation

OAuth 2.0

The app's integration key and a secret key from DocuSign's Apps and Keys page.

For: How Roster signs in: Sign in with Connect.

Requested scopes:

  • signature
  • extended

Connection fields

DocuSign connection fields
FieldWhat to provide
How Roster signs in
signIn
Optional		JWT lets Roster act as one DocuSign user without anyone signing in again. Signing in with Connect uses a person's own DocuSign sign-in.

Choices: JWT (an app's RSA key, acting as one user) (jwt); Sign in with Connect (oauth).

Starts with: jwt.

RSA private key
privateKey
Optional · sealed secret		The private key of the RSA key pair you added to the app in DocuSign, from -----BEGIN to -----END.

Shown when signIn: jwt.

OAuth app client secret
clientSecret
Optional · sealed secret		Use the value for your account or connection.

Shown when signIn: oauth.

DocuSign environment
environment
Optional		Use the value for your account or connection.

Choices: Developer (demo) (demo); Production (production).

Starts with: production.

Integration key
clientId
Optional		The app's integration key, from DocuSign's Apps and Keys page.
User ID
userId
Optional		The DocuSign user hires act as (Apps and Keys → User ID). Envelopes are sent in their name, so use a user named for your team.

Shown when signIn: jwt.

Account
accountId
Optional		Only if the user has more than one DocuSign account: its ID or name. Empty: their default account.
Business name
businessName
Required		The signing email's message speaks in this name. Never a made-up person's name.
Documents hires may see
visibility
Optional		E-signature accounts hold contracts, offers and HR papers. By default hires see only what they drafted or sent through Roster.

Choices: Only documents made through Roster (roster); Every document this account can see (all).

Starts with: roster.

Connect HMAC key
connectKey
Optional · sealed secret		Optional: a Connect key (Settings → Connect → Connect keys) of a configuration sending JSON to this connection's address with HMAC on. Signatures then wake hires at once.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

DocuSign per-hire limits
FieldWhat to provide
Templates
templates
Optional		Template names or IDs it may use. Leave empty for every template.
Who it may send to
signers
Optional		Email domains or full addresses it may send documents to. Leave empty for anyone (sending always asks a person first).

Actions

6 actions: 4 only read and 2 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

6 of 6 actions. Open an action for its arguments and full input schema.

list_templatesRead only

DocuSign templates this hire may send, with the roles each one needs filled.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
list_documentsRead only

Documents in DocuSign, newest first: their status and how many have signed. By status (draft, sent, completed, declined, voided, expired) or words in the title.

Approval: Uses your workspace and hire approval settings.

Arguments for list_documents
ArgumentTypeDetails
statusOptional"draft" | "sent" | "completed" | "declined" | "voided" | "expired"See input schema below.
wordsOptionalstringSee input schema below.
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "sent",
        "completed",
        "declined",
        "voided",
        "expired"
      ]
    },
    "words": {
      "type": "string",
      "maxLength": 200
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  }
}
get_statusRead only

A document's status in DocuSign, with each signer's: waiting, viewed, signed or declined (and why).

Approval: Uses your workspace and hire approval settings.

Arguments for get_status
ArgumentTypeDetails
documentRequiredstringthe document's ID
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "document": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "the document's ID"
    }
  },
  "required": [
    "document"
  ]
}
signed_copyRead only

The signed PDF of a completed DocuSign document, as a reference: its name, size and SHA-256 fingerprint, and where people download it. Hires never get the file itself.

Approval: Uses your workspace and hire approval settings.

Arguments for signed_copy
ArgumentTypeDetails
documentRequiredstringthe document's ID
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "document": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "the document's ID"
    }
  },
  "required": [
    "document"
  ]
}
create_draftRead and write

Prepare a document from a template as a draft in DocuSign, for a person to check and send. Nobody receives anything.

Approval: Uses your workspace and hire approval settings.

Arguments for create_draft
ArgumentTypeDetails
templateRequiredstringthe template's name or ID, from list_templates
titleRequiredstringthe document's title, as signers will see it
signersRequiredobject[]See input schema below.
subjectOptionalstringthe signing email's subject
messageOptionalstringthe signing email's message, plain text
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "template": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "the template's name or ID, from list_templates"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "the document's title, as signers will see it"
    },
    "signers": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "the template's role this person fills, as list_templates shows"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "email": {
            "type": "string",
            "format": "email",
            "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
          }
        },
        "required": [
          "role",
          "name",
          "email"
        ]
      }
    },
    "subject": {
      "description": "the signing email's subject",
      "type": "string",
      "maxLength": 200
    },
    "message": {
      "description": "the signing email's message, plain text",
      "type": "string",
      "maxLength": 2000
    }
  },
  "required": [
    "template",
    "title",
    "signers"
  ]
}
send_for_signatureRead and write

Make a document from a template and send it for signature: every signer gets DocuSign's email with your subject and message. It's a commitment in your business's name, so it waits for a person's approval: Roster asks in the thread with everything below, and sends exactly that, once, when they approve. It goes out in the business's name: write as the business, never sign with a person's name or say you're one.

Approval: Always asks for approval.

Arguments for send_for_signature
ArgumentTypeDetails
templateRequiredstringthe template's name or ID, from list_templates
titleRequiredstringthe document's title, as signers will see it
signersRequiredobject[]See input schema below.
subjectOptionalstringthe signing email's subject
messageOptionalstringthe signing email's message, plain text
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "template": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "the template's name or ID, from list_templates"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "the document's title, as signers will see it"
    },
    "signers": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "the template's role this person fills, as list_templates shows"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "email": {
            "type": "string",
            "format": "email",
            "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
          }
        },
        "required": [
          "role",
          "name",
          "email"
        ]
      }
    },
    "subject": {
      "description": "the signing email's subject",
      "type": "string",
      "maxLength": 200
    },
    "message": {
      "description": "the signing email's message, plain text",
      "type": "string",
      "maxLength": 2000
    }
  },
  "required": [
    "template",
    "title",
    "signers"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • Incoming webhooks are supported. Use the callback address shown on the connection and follow the setup guide.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

Documenso

Let hires send documents from your Documenso templates for signature, after a person approves, follow who has signed, and be woken when a document is signed.

Dropbox Sign

Signature requests and templates in Dropbox Sign.

On this page

1. Make an app in DocuSign2. Connect it in Roster3. Give hires access4. Get told when envelopes are signed (optional)Saying it's an AI assistantTools and permissions reference