Authentication

You can authenticate with the HelloSign 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 HelloSign 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: JWT(JSON Web Token)

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 HelloSign 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 HelloSign 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 HelloSign 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 HelloSign 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 HelloSign API keys:

  • API keys cannot be transferred between HelloSign 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
Screenshot showing the api dashboard and location of the Generate key button.
  • Enter name for new API key.
  • Click Generate key.
Screenshot showing a modal where users name new HelloSign api keys.
🔚 🏁
Result:
  • New key added to API key table.
  • Click Generate key.
Screenshot showing the api dashboard with the new API key listed on the API key table.

Delete API Key

StepScreenshot
  • Go to your API Settings page.
  • Click the row's menu button ("⋮").
  • Click Delete.
Screenshot showing the api dashboard and location of the Delete key button.
  • Confirm you want to delete the key.
  • Click Delete.
Screenshot showing a modal where users confirm deletion of api keys.
🔚 🏁
Result:
  • API key removed from table.
  • Displays temporary confirmation.
Screenshot showing the api dashboard with a confirmation banner of key being deleted.

Rename API Key

StepScreenshot
  • Go to your API Settings page.
  • Click the row's menu button ("⋮").
  • Click Rename.
Screenshot showing the api dashboard and location of the Rename key button.
  • Enter new key name.
  • Click done.
Screenshot showing a modal with the key being renamed.
🔚 🏁
Result:
  • API key shows new name.
  • Displays temporary confirmation.
Screenshot showing the api dashboard with a confirmation banner of key being renamed.

Choose Primary Key

StepScreenshot
  • Go to your API Settings page.
  • Click the row's menu button ("⋮").
  • Click Make primary.
Screenshot showing the api dashboard and location of the Primary key button.
  • Check that your app is ready
    to verify the event_hash
    using the new key.
  • Click Make primary.
Screenshot showing a modal confirming you want to make the key primary.
🔚 🏁
Result:
  • API key marked as primary.
  • The event_hash sent with
    event data is based on new key.
Screenshot showing the api dashboard with new key marked as primary.

Rotating API Keys

StepScreenshot
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. Screenshot showing the api settings page and location of api key table.
2. Press the Generate key button above the API key table. Screenshot of location of the Generate key button on api settings page.
3. Name the new key and press Generate key. Screenshot of modal to name new 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.
Screenshot showing location of new key on api settings page.
5. Update your code so API calls to HelloSign 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 HelloSign 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.
Screenshot showingl ocation of primary key button.
7. Verify you updated your event verification and click Make primary. Screenshot of modal to confirm change of primary key.
8. Interact with the HelloSign features as a user would. Verify two behaviors:
  • API calls are working.
  • Event payloads are being processed correctly.
Screenshot showing timestamp of when new primary key as used last.
🔚 🏁
Result:
  • Your integration with the HelloSign 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 HelloSign API by including the test_mode parameter in your request. HelloSign 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.