Send On Behalf Of (SOBO) Authentication

Originally designed to send envelopes on behalf of other users in an account, Send On Behalf Of (SOBO) is an authentication method that allows a user (the authenticating user) to send envelopes and to perform almost any task in the name of another user (the operating user) in the same account.

When to Use SOBO

SOBO is designed to assist developers with two specific authentication use cases:

  • User applications that cannot authenticate the operating user.

    In user applications you would typically use one of the OAuth2 authentication flows: Authorization Code Grant or Implicit Code Grant to authenticate the user. But if your application can’t use one of these flows, you can use SOBO authentication with a dedicated authenticating account to send envelopes or perform other tasks on behalf of the operating users.

  • Service integrations that do not have access to the operating user.

    Imagine an integration that that works with your CRM system to send envelopes to new customers. You want the envelopes to come from the new customer’s account executive, but you don’t the account executive to log in to, or even interact, with this integration. In this case you might use SOBO authenticating with an account dedicated to the integration and setting the account executive as the operating users.

Required Permissions

The authenticating user must have the following user setting properties set to true:

  • apiAccountWideAccess: Specifies that the user can send and manage envelopes for the entire account using the DocuSign API.
  • allowSendOnBehalfOf: Specifies that the user can send envelopes and perform other tasks on behalf of other users through the API.

In the New DocuSign Admin experience, these settings are in the the Permission Sets section as Allow view and manage envelope rights through API and Allow send on behalf of other users through API. These settings are on by default for the DS Admin permission set.

In the Classic DocuSign Admin experience, you can find these settings in the Member Options section as Account-Wide Rights and Send On Behalf Of Rights (API).

Using SOBO with Legacy Header Authentication

If you are using Legacy Authentication use the SendOnBehalfOf field in the X-DocuSign-Authentication header to specify the operating user. In the following examples nat.irving@example.com is the authenticating user, and ruggiero.gardener@example.com is the operating user.

JSON header

{
  "Username": "nat.irving@example.com",
  "Password": "S3cre+p455w0Rd",
  "IntegratorKey": "230546a7-9c55-40ad-8fbf-af205d5494ad",
  "SendOnBehalfOf": "ruggiero.gardener@example.com"
}

XML header

<DocuSignCredentials>
  <Username>nat.irving@example.com</Username>
  <Password>S3cre+p455w0Rd</Password>
  <IntegratorKey>230546a7-9c55-40ad-8fbf-af205d5494ad</IntegratorKey>
  <SendOnBehalfOf>ruggiero.gardener@example.com</SendOnBehalfOf>
</DocuSignCredentials>

The value of the SendOnBehalfOf field can be:

  • a properly formatted email address, optionally followed by a semicolon and a user name
  • a user ID

The platform looks up the operating user’s email or user ID to make sure that it is a member of the authenticating user’s account.

It is an error if the authenticating user does not have the appropriate permissions or if the operating user is not a member of the account.

Example: Creating an Envelope with SOBO

In this example, the authenticating user nat.irving@example.com is sending an envelope to the recipients on behalf of the operating user ruggiero.gardener@example.com.

POST /restapi/v2/accounts/1703061/envelopes
X-DocuSign-Authentication: { "Username":"nat.irving@example.com", "Password":"S3cre+p455w0Rd", "IntegratorKey":"230546a7-9c55-40ad-8fbf-af205d5494ad", "SendOnBehalfOf": "ruggiero.gardener@example.com"}
Content-Type: application/json

{
  "documents": [
    {
      "documentBase64": "[encoded document bytes]",
      "documentId": "1",
      "fileExtension": "pdf",
      "name": "NDA.pdf"
    }
  ],
  "emailSubject": "Please sign the NDA",
  "recipients": {
    . . .
  },
  "status": "sent"
}

Methods That Do Not Support SOBO

The following methods do not support SOBO.

Errors

If there is an error, the response satus is 401 Unauthorized. The error message gives more detail.

If the authenticating user does not have the appropriate permissions, the error is USER_LACKS_PERMISSIONS:

{
  "errorCode": "USER_LACKS_PERMISSIONS",
  "message": "This user lacks sufficient permissions to access this resource."
}

If the operating user is not a member of the account, the error is USER_LACKS_MEMBERSHIP:

{
  "errorCode": "USER_LACKS_MEMBERSHIP",
  "message": "The UserID does not have a valid membership in this Account."
}