Send On Behalf Of Functionality

The Send On Behalf Of feature permits automated sending through the API by an integrated sender on behalf of another user. SOBO functionality is only available to accounts that use the DocuSign API to send envelopes. It can be enabled for an account member by a DocuSign Customer Administrator through the DocuSign Console or by contacting your DocuSign Account Manager.

A user, known as the authenticating user in this circumstance, that wants to authenticate for other users in the account must have the following DocuSign userSettings enabled for SOBO functionality:

  • apiAccountWideAccess
  • allowSendOnBehalfOf

Note: 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.

This allows an authenticating user to act as another user in the account, so the client application does not have to track the passwords for individual users. Instead, only the authenticating user's information is used. The operations, usually sending an envelope or checking status, are performed as the "operating user," not as the authenticating user. The authenticating user's information is used for authentication only, while the "operating user's" userId is checked for proper authorization for the API method being called.

OAuth and SOBO

Implementation of SOBO functionality in your applications requires the use of access tokens generated by OAuth. For example, let's say that User 1 wants to send requests on behalf of User 2. These users need to be members of the same account and User 1 needs to have the account options mentioned above enabled.

The general steps to accomplish this are:

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

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.

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

(headers)

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

(body)

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

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

{
        "access_token": "<access token for user>",
        "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 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.

For more information on OAuth support please see this page of the online REST API Guide. For more information on SOBO functionality see this page.