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.

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):

Copy
Copied
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:

Copy
Copied
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>.
Copy
Copied
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.

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

StepScreenshot