SOBO - Send On Behalf Of Functionality

The Send On Behalf Of feature permits automated sending through the API by one account user on behalf of another account user. Users who want to authenticate on behalf of other account users must have the following settings enabled to use SOBO:

  • apiAccountWideAccess
  • allowSendOnBehalfOf

If you are setting user permissions through the DocuSign web console these correspond to the Account-Wide Rights and Send On Behalf Of Rights (API) settings.

SOBO Process

Let's say that User 1 wants to send requests on behalf of User 2. These users need to be members of the same DocuSign account and User 1 needs to have the above account options enabled.

The general steps to accomplish this are:

  1. Obtain an access token for User 1
  2. Obtain an access token for User 2
  3. Send Request on behalf of User 2

However it's likely that you will only have to take the first two steps once since access token do not expire (if you want to delete them you have to make to an API call to revoke). In other words, once you have a token generated for User2 you can skip directly to the third step of making requests on behalf of that user.

Step 1: Obtain access token for the authenticating user (User 1)

To obtain a user access token for User 1 make the following API call:

POST https://{server}/restapi/{apiVersion}/oauth2/token

Accept: application/json
Content-Type: application/x-www-form-urlencoded
Content-Length: {length of body}

grant_type=password&client_id={IntegratorKey}&username={email}&password={password}&scope=api

A successful call generates an http 200 response with the following body:

{
    "access_token": "11111",
    "scope": "api",
    "token_type": "bearer"
}

For simplicity let's say the token that was returned for User 1 is "11111". Once obtained, this access_token should be stored with the individual user's information and protected from unauthorized use, since it will remain valid until revoked. It will be valid across user password changes as well.

Step 2: Obtain access token for the operating user (User 2)

Next we need to obtain a user access token for User 2, by making the following API call. Note the additional Authorization header in the request:

POST https://{server}/restapi/{apiVersion}/oauth2/token

Authorization: bearer 11111
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Content-Length: {length of body}

grant_type=password&client_id={IntegratorKey}&username={operatingUser}&password={password}&scope=api

The format of the Authorization header is

Authorization: bearer <access_token>

Here we put the string bearer followed by the actual access_token value that was returned in the first step (i.e. 11111). The value contained in the variable operatingUser in the body of this request is the userId or email address of User 2 (aka the user we will send on behalf of). Let's say that the access token returned from this call is "22222".

Step 3: Send signature request on behalf of User 2

Now that we have a user access token for User 2, we can use it to make requests on behalf of this user. To do so, we'll include an Authorization header once again only this time it will contain the access token for User 2, and we will also add an additional header called X-DocuSign-Act-As-User. To make a signature request on behalf of User 2 we would make the following call:

POST https://{server}/restapi/{apiVersion}/accounts/{ACCOUNTID}/envelopes

Authorization: bearer 22222
X-DocuSign-Act-As-User: $emailOnBehalf
Accept: application/json
Content-Type: multipart/form-data;boundary=MYBOUNDARY
Content-Length: {length of body}

<request body with your envelope definition goes here>

The X-DocuSign-Act-As-User header, which contains the email address for User2, is added to the request and so is the Authorization header with the access token for User 2.