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.

For terminology details, see the glossary entry for Authentication Methods.

Try it console auth

The “Try it console”, used for sending live API calls from these docs, only supports authenticating with your API key.

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:

🟢 Do These 🟢	🔴 Don’t Do These 🔴
Give your API key a descriptive name. Treat all API keys like a very important password you need to keep safe. Use an environment file or credential manager to store your API key outside of your code. Immediately rotate API keys if you suspect a breach or exposure. Periodically rotate your API key on an annual basis as a proactive security measure. Keep minimum number of API keys as possible. Always remove keys that are inactive or serving a temporary need.	Never share your API key with others. It’s not safe. Instead, use OAuth for providing delegated access. Don’t put your API key in your source code. Don’t store your API key on the client side.

🟢 Do These 🟢

🔴 Don’t Do These 🔴

Give your API key a descriptive name.
Treat all API keys like a very important password you need to keep safe.
Use an environment file or credential manager to store your API key outside of your code.
Immediately rotate API keys if you suspect a breach or exposure.
Periodically rotate your API key on an annual basis as a proactive security measure.
Keep minimum number of API keys as possible.
Always remove keys that are inactive or serving a temporary need.

Never share your API key with others. It’s not safe. Instead, use OAuth for providing delegated access.
Don’t put your API key in your source code.
Don’t store your API key on the client side.

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

My API key was compromised, what should I do?

Do you suspect a breach?

Yes — Create new key and delete the compromised credentials immediately. You can fix your integration right after with minimal down time.
No — Rotate your API key as soon as possible.

When does my API key expire?

API keys are long-lived and do not expire. However, access tokens, which are used for OAuth, expire after an hour and can be regenerated using a refresh token.

How do I get an API key for testing?

Any valid API key can be used for testing the Dropbox Sign API by including the test_mode parameter in your request. Dropbox Sign doesn’t support different types of API keys, testing or otherwise.

How often should I rotate my API key?

We recommend rotating API keys at least once a year, but you can adjust the frequency to fit your security requirements.