See More

> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.hellosign.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.hellosign.com/_mcp/server. > Learn about how the Dropbox Sign API implements authentication to protect user data. # 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](/api/manual-reference-pages/glossary/security-compliance#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](https://app.hellosign.com/home/myAccount#api).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): ```shell 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: ```shell 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 `. ```shell 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](/docs/oauth/overview/#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](/docs/oauth/walkthrough) for additional information. ## Multiple API Keys In order to allow [rotating API keys](#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](/docs/guides/events-and-callbacks/walkthrough/#event-hash-verification). ### Best Practices We recommend the following best practices when using Dropbox Sign API keys: | 🟢 Do These 🟢 | 🔴 Don't Do These 🔴 | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

| | ### 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](/docs/oauth/overview/) 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 | | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | ![Screenshot showing the api dashboard and location of the Generate key button.](file:docs/api-reference/api-images/generate-key.png "#width=650px;") | | | ![Screenshot showing a modal where users name new Dropbox Sign api keys.](file:docs/api-reference/api-images/generate-key-name.png "#width=650px;") | | 🔚 🏁
**Result:**
| ![Screenshot showing the api dashboard with the new API key listed on the API key table.](file:docs/api-reference/api-images/generate-key-result.png "#width=650px;") | ### Delete API Key | Step | Screenshot | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | ![Screenshot showing the api dashboard and location of the Delete key button.](file:docs/api-reference/api-images/delete-key-menu.png "#width=650px;") | | | ![Screenshot showing a modal where users confirm deletion of api keys.](file:docs/api-reference/api-images/delete-key-confirm.png "#width=650px;") | | 🔚 🏁
**Result:**
| ![Screenshot showing the api dashboard with a confirmation banner of key being deleted.](file:docs/api-reference/api-images/delete-key-result.png "#width=650px;") | ### Rename API Key | Step | Screenshot | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | ![Screenshot showing the api dashboard and location of the Rename key button.](file:docs/api-reference/api-images/rename-key-menu.png "#width=650px;") | | | ![Screenshot showing a modal with the key being renamed.](file:docs/api-reference/api-images/rename-key-confirm.png "#width=650px;") | | 🔚 🏁
**Result:**
| ![Screenshot showing the api dashboard with a confirmation banner of key being renamed.](file:docs/api-reference/api-images/rename-key-result.png "#width=650px;") | ### Choose Primary Key | Step | Screenshot | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | | ![Screenshot showing the api dashboard and location of the Primary key button.](file:docs/api-reference/api-images/primary-key-menu.png "#width=650px;") | | | ![Screenshot showing a modal confirming you want to make the key primary.](file:docs/api-reference/api-images/primary-key-confirm.png "#width=650px;") | | 🔚 🏁
**Result:**
| ![Screenshot showing the api dashboard with new key marked as primary.](file:docs/api-reference/api-images/primary-key-result.png "#width=650px;") | ### Rotating API Keys | Step | Screenshot | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1. Under the API key section of your [API Settings](https://app.hellosign.com/home/myAccount?current_tab=integrations#api) page, you'll see a table with columns that display your API key's information. | ![Screenshot showing the api settings page and location of api key table.](file:docs/api-reference/api-images/rotate-key-step-one.png "#width=650px;") | | 2. Press the **Generate key** button above the API key table. | ![Screenshot of location of the Generate key button on api settings page.](file:docs/api-reference/api-images/rotate-key-step-two.png "#width=650px;") | | 3. Name the new key and press **Generate key**. | ![Screenshot of modal to name new key.](file:docs/api-reference/api-images/rotate-key-step-three.png "#width=650px;") | | 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.** | ![Screenshot showing location of new key on api settings page.](file:docs/api-reference/api-images/rotate-key-step-four.png "#width=650px;") | | 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)](/docs/guides/events-and-callbacks/overview/) must update their [event hash verification](/docs/guides/events-and-callbacks/walkthrough/#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](https://app.hellosign.com/home/myAccount?current_tab=integrations#api) page. | ![Screenshot showingl ocation of primary key button.](file:docs/api-reference/api-images/rotate-key-step-six.png "#width=650px;") | | 7. Verify you updated your [event verification](/docs/guides/events-and-callbacks/walkthrough/#event-hash-verification) and click **Make primary**. | ![Screenshot of modal to confirm change of primary key.](file:docs/api-reference/api-images/rotate-key-step-seven.png "#width=650px;") | | 8. Interact with the Dropbox Sign features as a user would. Verify two behaviors:
Once confirmed, the end result is:
| ![Screenshot showing timestamp of when new primary key as used last.](file:docs/api-reference/api-images/rotate-key-step-eight.png "#width=650px;") | ## Frequently Asked Questions (FAQs) Answers to commonly asked questions. When in doubt, please reach out to [[email protected]](mailto:[email protected]) #### 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](#rotating-api-keys) 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](/docs/oauth/overview/), expire after an hour and can be regenerated using a [refresh token](/api/reference/operation/oauthTokenRefresh/). #### 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.