Authentication

You can authenticate with the Dropbox Sign API in two ways: using an API key or an access token issued through an OAuth flow.

API Key

The most common method of authenticating against the Dropbox Sign API is by using API keys, which can be retrieved from the API tab of your API Settings page.This approach uses a “Basic” HTTP Authentication Scheme where the API key is passed as the username and the password is left blank. Example (note the trailing ”:” after the API key):

$
API_KEY=YOUR_SECRET_API_KEY_HERE
$
curl "https://api.hellosign.com/v3/template/list" \
>
    -u "${API_KEY}:"

Alternatively, you can pass the API key as part of the URL:

$
API_KEY=YOUR_SECRET_API_KEY_HERE
$
curl "https://${API_KEY}:@api.hellosign.com/v3/template/list"

Security Scheme Type: HTTP HTTP Authorization Scheme: Basic

Access Token

You can use an access token (issued during an OAuth flow) to send API requests on behalf of the user that granted authorization. Passed as in the header of a request as an Authorization parameter using the following format: Bearer <access_token>.

$
ACCESS_TOKEN=ACCESS_TOKEN_GRANTED_BY_OAUTH
$
curl 'https://api.hellosign.com/v3/signature_request/list' \
>
   -H "Authorization: Bearer ${ACCESS_TOKEN}"

Security Scheme Type: HTTP HTTP Authorization Scheme: Basic Bearer format: base64 encoded string

Notes about OAuth The permissions applied to access tokens are controlled by the access scopes set in your API app. Those scopes are shown to the end-user completing an OAuth flow. Please refer to our OAuth Walkthrough for additional information.

Multiple API Keys

In order to allow rotating API keys, the Dropbox Sign API supports the creation of multiple API keys. Periodically rotating the API key used in your integration is a good security practice that helps protect your users.

Each Dropbox Sign account (regardless of subscription tier) may have up to four API keys at a time. All keys are “active” and can be used to call the Dropbox Sign API, but only one key at a time can be set as the Primary Key. The Primary Key is used to generate the event_hash, which serves to verify event payloads.

Best Practices

We recommend the following best practices when using Dropbox Sign API keys:

Limitations

At the time of writing (Sept. 2022), the following limitations apply to Dropbox Sign API keys:

• API keys cannot be transferred between Dropbox Sign accounts.
• The maximum number of API keys per account is limited to 4.
• An API key cannot be set to expire.
• API key permissions cannot be restricted. Use OAuth if you need scoped access.

API Key Management

This section contains information to help users manage their API keys.

Generate New API Key

Step	Screenshot
Go to your API Settings page. Click Generate key.
Enter name for new API key. Click Generate key.
🔚 🏁 Result: New key added to API key table. Click Generate key.

Delete API Key

Step	Screenshot
Go to your API Settings page. Click the row’s menu button (”⋮”). Click Delete.
Confirm you want to delete the key. Click Delete.
🔚 🏁 Result: API key removed from table. Displays temporary confirmation.

Rename API Key

Step	Screenshot
Go to your API Settings page. Click the row’s menu button (”⋮”). Click Rename.
Enter new key name. Click done.
🔚 🏁 Result: API key shows new name. Displays temporary confirmation.

Choose Primary Key

Step	Screenshot
Go to your API Settings page. Click the row’s menu button (”⋮”). Click Make primary.
Check that your app is ready to verify the event_hash using the new key. Click Make primary.
🔚 🏁 Result: API key marked as primary. The event_hash sent with event data is based on new key.

Rotating API Keys

Step	Screenshot
1. Under the API key section of your API Settings page, you’ll see a table with columns that display your API key’s information.
2. Press the Generate key button above the API key table.
3. Name the new key and press Generate key.
4. The new key appears on the API key table. Your previous key is still designated as the “Primary Key”. Don’t change primary key yet.
5. Update your code so API calls to Dropbox Sign use the new key. Does your app use Events and Callbacks? —> Yes — you have an extra step. See right column. —> No — move to next step.	Any apps using Dropbox Sign Events (webhooks) must update their event hash verification to use the new API key to avoid a disruption in service. The event_hash included in event payloads is generated based on the API key set to Primary Key.
6. Return to your API Settings page. Click the row’s menu button (”⋮”). Click Make primary.
7. Verify you updated your event verification and click Make primary.
8. Interact with the Dropbox Sign features as a user would. Verify two behaviors: API calls are working. Event payloads are being processed correctly. Once confirmed, the end result is: Your integration with Dropbox Sign API uses a new API key. Service to your end users was not disrupted.

Frequently Asked Questions (FAQs)

Answers to commonly asked questions. When in doubt, please reach out to apisupport@hellosign.com