Explore our blog

API Bytes: Onboarding your cloud storage provider

Maybe you're asking, "Who cares about the cloud?" To which I respond, "Who doesn't!" In this post I’m going to show you how to connect your DocuSign integration with popular cloud storage providers.

Cloud storage providers offer the means to back up and store your files across the web, powered through the technology of cloud computing. Storing your own completed DocuSign envelopes is, in and of itself, a mechanism that uses DocuSign servers as a cloud storage provider. DocuSign offers integrations we support through eSignature that enable you to connect your DocuSign account to the following cloud storage providers: Google Drive, Dropbox, DocuSign Rooms, Box, and Salesforce. If you already have services connected through them or documents and process infrastructure built in on those platforms, why not leverage them? Imagine, for instance, a scenario where you want to keep an entire document store in the cloud. The DocuSign eSignature REST API enables you directly to verify document availability on a cloud storage provider without the need for a separate SDK or OAuth process.

Request an authorization URL for your cloud storage provider

To use one of the cloud storage providers I've mentioned, make the API call shown in the code below to request an authorization URL. You'll need to specify the service name and your application's callback URL, so your application can continue through its own processes. If your service name happens to include two or more words, such as "Google Drive", remove the space and set the name to lowercase, such that "Google Drive" becomes "googledrive".

Bash

# Retrieve authorization URLs
 
oAuthAccessToken="eyJ0eXAiOiJKV1QiLCJhbGciOiJSU.....mWD0yY6sztXipERLlTbdNjCRjruRsVFaw"
AccountId="2255f473-xxxx-xxxx-xxxx-c07c9abc6d76"
 
# A UserId is needed to associate a specific account user within your account or organization to your cloud storage provider. The UserId is a GUID value that uniquely identifies a DocuSign user. See https://developers.docusign.com/platform/configuring-app/ for details.
UserId="95461dce-xxxx-xxxx-xxxx-68acae2ab5c0"
 
# Construct your envelope JSON body
printf \
'{
  "storageProviders": [
    {
      "redirectUrl": "localhost:8080/callback",
      "service": "dropbox"
    },
    {
      "redirectUrl": "localhost:8080/callback",
      "service": "skydrive"
    }
  ]
}' >> $request_data
 
base_path="https://demo.docusign.net/restapi"
 
# Construct your API headers
declare -a Headers=('--header' "Authorization: Bearer ${oAuthAccessToken}" \
                    '--header' "Accept: application/json" \
                    '--header' "Content-Type: application/json" )
 
 
# Call the eSignature REST API
Status=$(curl -w '%{http_code}' -i --request POST https://demo.docusign.net/restapi/v2.1/accounts/${accountId}/users/${userId}/cloud_storage \
     "${Headers[@]}" \
     --data-binary ${request_data} \
     --output ${response})
 
# If the Status code returned is greater than 201 (OK/Accepted), display an error message along with the API response
if [[ "$Status" -gt "201" ]] ; then
    echo ""
    echo "Failed to retrieve cloud provider authorization URLs"
    echo ""
    cat $response
    exit 1
fi
 
echo "Cloud provider urls:"
cat $response
 
# Remove the temporary files
rm "$request_data"
rm "$response"

C#

// Retrieve authorization URLS 

var basePath = "https://demo.docusign.net/restapi/v2.1/accounts/restapi";
var accessToken = "eyJ0eXAiOiJKV1QiLCJhbGciOiJSU.....mWD0yY6sztXipERLlTbdNjCRjruRsVFaw";
var AccountId = "2255f473-xxxx-xxxx-xxxx-c07c9abc6d76";

// A UserId is needed to associate a specific account user within your account or organization to your cloud storage provider. The UserId is a GUID value that uniquely identifies a DocuSign user. See https://developers.docusign.com/platform/configuring-app/ for details.
var userId = "95461dce-xxxx-xxxx-xxxx-68acae2ab5c0";

// Construct your API headers
var apiClient = new ApiClient(basePath);
apiClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
CloudStorageApi CloudStorage = new CloudStorageApi(apiClient);
CloudStorageProviders storageProviders = new CloudStorageProviders();
storageProviders.StorageProviders.Add(new CloudStorageProvider { Service = "dropbox", RedirectUrl = "localhost:8080/callback", });
storageProviders.StorageProviders.Add(new CloudStorageProvider { Service = "googledrive", RedirectUrl = "localhost:8080/callback", });

// Call the eSignature REST API
CloudStorage.CreateProvider(AccountId, userId, storageProviders);

Java

String oAuthAccessToken = "eyJ0eXAiOiJKV1QiLCJhbGciOiJSU.....mWD0yY6sztXipERLlTbdNjCRjruRsVFaw";
String AccountId = "2255f473-xxxx-xxxx-xxxx-c07c9abc6d76";

// A UserId is needed to associate a specific account user within your account or organization to your cloud storage provider. The UserId is a GUID value that uniquely identifies a DocuSign user. See https://developers.docusign.com/platform/configuring-app/ for details.
String userId = "95461dce-xxxx-xxxx-xxxx-68acae2ab5c0";
String basePath ="https://demo.docusign.net/restapi";

// Construct your API headers
ApiClient apiClient = new ApiClient(basePath);
apiClient.addDefaultHeader(HttpHeaders.AUTHORIZATION, BEARER_AUTHENTICATION + oAuthAccessToken);
CloudStorageApi CloudStorage = new CloudStorageApi(apiClient); 
CloudStorageProvider sp1 = new CloudStorageProvider();
sp1.setService("googledrive");
sp1.setRedirectUrl("localhost:8080/callback");
CloudStorageProvider sp2 = new CloudStorageProvider();
sp1.setService("dropbox");
sp1.setRedirectUrl("localhost:8080/callback");
CloudStorageProviders csp = new CloudStorageProviders();
csp.addStorageProvidersItem(sp1);
csp.addStorageProvidersItem(sp2);

// Call the eSignature REST API
CloudStorage.createProvider(AccountId, userId, csp);

Node.js

// Retrieve authorization URLs
let oAuthAccessToken = "eyJ0eXAiOiJKV1QiLCJhbGciOiJSU.....mWD0yY6sztXipERLlTbdNjCRjruRsVFaw";
let AccountId = "2255f473-xxxx-xxxx-xxxx-c07c9abc6d76";
let basePath = "https://demo.docusign.net/restapi";
 
// A UserId is needed to associate a specific account user within your account or organization to your cloud storage provider. The UserId is a GUID value that uniquely identifies a DocuSign user. See https://developers.docusign.com/platform/configuring-app/ for details.
let userId = "95461dce-xxxx-xxxx-xxxx-68acae2ab5c0";
 
// Construct your API headers
let dsApiClient = new docusign.ApiClient();
dsApiClient.setBasePath(basePath);
dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + oAuthAccessToken);
 
let CloudStorageApi = new docusign.CloudStorageApi(dsApiClient);
let CloudStorageProvider = new docusign.CloudStorageProvider({
    Service = "dropbox",
    RedirectUrl = "localhost:8080/callback"
});
let CloudStorageProviderB = new docusign.CloudStorageProvider({
    Service = "skydrive",
    RedirectUrl = "localhost:8080/callback"
});
 
// Call the eSignature REST API
CloudStorageApi.createProvider(AccountId, userId, [CloudStorageProvider, CloudStorageProviderB]).then((res)=>{ console.log(res) });

PHP

# Retrieve authorization URLs
$oAuthAccessToken="eyJ0eXAiOiJKV1QiLCJhbGciOiJSU.....mWD0yY6sztXipERLlTbdNjCRjruRsVFaw";
 
# A UserId is needed to associate a specific account user within your account or organization to your cloud storage provider. The UserId is a GUID value that uniquely identifies a DocuSign user. See https://developers.docusign.com/platform/configuring-app/ for details.
$UserId="95461dce-xxxx-xxxx-xxxx-68acae2ab5c0";
$AccountId="2255f473-xxxx-xxxx-xxxx-c07c9abc6d76";
$base_path="https://demo.docusign.net/restapi";
 
# Construct your API headers
$config = new Configuration();
$config->setHost($base_path);
$config->addDefaultHeader('Authorization', 'Bearer ' . $oAuthAccessToken);    
$apiClient = new ApiClient($config);
$CloudStorageApi = new CloudStorageApi($apiClient);
$dropbox = new CloudStorageProvider(["service"=>"dropbox", "redirectUrl"=>"localhost:8080/callback" ]);
$skydrive = new CloudStorageProvider(["service"=>"skydrive", "redirectUrl"=>"localhost:8080/callback" ]);
$csp = new CloudStorageProviders([$dropbox, $skydrive]);
 
# Call the eSignature REST API
$CloudStorageApi->createProvider($AccountId, $UserId,$csp);

PowerShell

# Retrieve authorization URLs
 
$oAuthAccessToken="eyJ0eXAiOiJKV1QiLCJhbGciOiJSU.....mWD0yY6sztXipERLlTbdNjCRjruRsVFaw"
$AccountId="2255f473-xxxx-xxxx-xxxx-c07c9abc6d76"
 
# A UserId is needed to associate a specific account user within your account or organization to your cloud storage provider. The UserId is a GUID value that uniquely identifies a DocuSign user. See https://developers.docusign.com/platform/configuring-app/ for details.
$UserId="95461dce-xxxx-xxxx-xxxx-68acae2ab5c0"
 
# Construct your API headers
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.add("Authorization", "Bearer $oAuthAccessToken")
$headers.add("Accept", "application/json")
$headers.add("Content-Type", "application/json")
 
# Construct your envelope JSON body
$body = @"
{
    "storageProviders": [
      {
        "redirectUrl": "localhost:8080/callback",
        "service": "dropbox"
      },
      {
        "redirectUrl": "localhost:8080/callback",
        "service": "skydrive"
      }
    ]
  }
"@
Write-Output ""
Write-Output "Request: "
Write-Output $body
 
# Call the eSignature REST API
$uri = "https://demo.docusign.net/restapi/v2.1/accounts/${AccountId}/users/${UserId}/cloud_storage"
 
# Trap errors in the response
try {
    Write-Output "Response:"
    $result = Invoke-WebRequest -uri $uri -headers $headers -body $body -method POST
    $result.content
}
catch {
    $int = 0
    foreach ($header in $_.Exception.Response.Headers) {
        if ($header -eq "X-DocuSign-TraceToken") { Write-Output "TraceToken : " $_.Exception.Response.Headers[$int] }
        $int++
    }
    Write-Output "Error : "$_.ErrorDetails.Message
    Write-Output "Command : "$_.InvocationInfo.Line
}

Python

# Get Authorization URLs
access_token = "eyJ0eXAiOiJKV1QiLCJhbGciOiJSU.....mWD0yY6sztXipERLlTbdNjCRjruRsVFaw"
base_path = "https://demo.docusign.net/restapi"
api_account_id = "2255f473-xxxx-xxxx-xxxx-c07c9abc6d76"
 
# A UserId is needed to associate a specific account user within your account or organization to your cloud storage provider. The UserId is a GUID value that uniquely identifies a DocuSign user. See https://developers.docusign.com/platform/configuring-app/ for details.
user_id = "95461dce-xxxx-xxxx-xxxx-68acae2ab5c0"
 
# Construct your API headers
api_client = create_api_client(base_path=base_path, access_token=access_token)
cloud_storage_api = CloudStorageApi(api_client)
dropbox = CloudStorageProvider(redirect_url="localhost:8080/callback", service="dropbox")
skydrive = CloudStorageProvider(redirect_url="localhost:8080/callback", service="skydrive")
csp = CloudStorageProviders([dropbox, skydrive])
 
# Call the eSignature REST API
CloudStorageApi.create_provider(api_account_id, user_id, csp)

Ruby

# Retrieve authorization URLs    
oAuthAccessToken = "eyJ0eXAiOiJKV1QiLCJhbGciOiJSU.....mWD0yY6sztXipERLlTbdNjCRjruRsVFaw"
base_path="https://demo.docusign.net/restapi"
api_account_id = "2255f473-xxxx-xxxx-xxxx-c07c9abc6d76"
 
# A UserId is needed to associate a specific account user within your account or organization to your cloud storage provider. The UserId is a GUID value that uniquely identifies a DocuSign user. See https://developers.docusign.com/platform/configuring-app/ for details.
user_id = "95461dce-xxxx-xxxx-xxxx-68acae2ab5c0"
 
 
configuration = DocuSign_eSign::Configuration.new
configuration.host = base_path
api_client = DocuSign_eSign::ApiClient.new configuration
 
# Construct your API headers
api_client.default_headers['Authorization'] = "Bearer #{oAuthAccessToken}"
cloud_storage_api = DocuSign_eSign::CloudStorageApi.new api_client
 
dropbox = DocuSign_esign::CloudStorageProvider.new
dropbox.service = "dropbox"
dropbox.redirect_url = "localhost:8080/callback"
 
skydrive = DocuSign_esign::CloudStorageProvider.new
skydrive.service = "skydrive"
skydrive.redirect_url = "localhost:8080/callback"
 
cloud_storage_providers = DocuSign_eSign::CloudStorageProviders.new
cloud_storage_providers << dropbox
cloud_storage_providers << skydrive
 
# Call the eSignature REST API
cloud_storage_api.create_provider(api_account_id, user_id, cloud_storage_providers)

The eSignature REST API will return an authorization URL that redirects first to your cloud service provider, then back to your application. Use this URL to register authorization and use of the cloud service provider and to grant consent for use. Similar to our own OAuth grant process, you're required to select the account and to allow it to authorize consent for use.

Retrieve a list of folders in cloud storage

Now you can use the CloudStorage: listFolders call to determine the various folder IDs (or perhaps collect the aggregate list and parse it post processing, if you happen to make a lot of moves with new users and folders).

Bash

curl --request GET "https://demo.docusign.net/restapi/v2.1/accounts/${account_id}/users/${user_id}/cloud_storage/${service_id}/folders/" \
      "${Headers[@]}" \
     --output ${response}

C#

CloudStorage.ListFolders(AccountId, userId, "googledrive");

Java

CloudStorage.listFolders(AccountId, userId, serviceId);

Node.js

CloudStorageApi.listFolders(AccountId, userId, serviceId ).then((res)=>{ console.log(res) });

PHP

CloudStorageApi->listFolders($AccountId, $serviceId, $UserId);

PowerShell

$uri = "https://demo.docusign.net/restapi/v2.1/accounts/${AccountId}/users/${UserId}/cloud_storage/${serviceId}/folders"

Python

CloudStorageApi.list_folders(api_account_id, service_id, user_id)

Ruby

cloud_storage_api.list_folders(api_account_id, service, user_id)

Retrieve file information from cloud folders

With the folder IDs in hand, you can then use the CloudStorage: list API call to retrieve the attribute information about the documents stored on your cloud storage provider. If your application has an Extract Transform Load (ETL) capability of some sort, then being able to parse the contents of your cloud storage providers is instrumental to those efforts.

Bash

curl --request GET "https://demo.docusign.net/restapi/v2.1/accounts/${account_id}/users/${user_id}/cloud_storage/${service_id}/folders/${folder_id}" \
      "${Headers[@]}" \
     --output ${response}

C#

CloudStorage.List(AccountId, userId, "googledrive", folderId);

Java

CloudStorage.list(AccountId, userId, serviceId, folderId);

Node.js

CloudStorageApi.list(AccountId, userId, serviceId,folderId).then((res)=>{ console.log(res) });

PHP

$CloudStorageApi->callList($AccountId, $folderId, $serviceId, $UserId)

PowerShell

$uri = "https://demo.docusign.net/restapi/v2.1/accounts/${AccountId}/users/${UserId}/cloud_storage/${serviceId}/folders/${folderId}"

Python

CloudStorageApi.list(api_account_id, folder_id, service_id, user_id)

Ruby

cloud_storage_api.list(api_account_id, folder_id, service, user_id)

And that's about as byte-sized as we can go this round. If you're looking for ways to harness external cloud storage providers within your own systems, use the eSignature REST API to ease headaches within your ETL process and stop having to juggle OAuth tokens.

We're always on the lookout for the next big question to be answered regarding DocuSign APIs. If you have a burning question or wish to see a concept outlined, don't hesitate to reach out via email with your comments or concerns to developers@docusign.com. We appreciate you.

Additional resources

Author

Aaron Jackson-Wilde

Programmer Writer

Published

July 1, 2021

API Bytes: Onboarding your cloud storage provider

Request an authorization URL for your cloud storage provider

Bash

C#

Java

Node.js

PHP

PowerShell

Python

Ruby

Retrieve a list of folders in cloud storage

Bash

C#

Java

Node.js

PHP

PowerShell

Python

Ruby

Retrieve file information from cloud folders

Bash

C#

Java

Node.js

PHP

PowerShell

Python

Ruby

Additional resources

Related Blog Posts

A new kind of Quickstart: Introducing the JWT Grant remote signing example

How to automate a workflow routine using aliases