HelloSign Authentication: API Keys & OAuth 2.0 (2026)

Authentication overview

HelloSign's API utilizes industry-standard authentication mechanisms to ensure secure and authorized access to its services. The choice of authentication method depends on the type of application and the nature of the integration. For server-side applications and scripts, API Keys offer a straightforward approach. For applications that require user consent to access their HelloSign data without handling their credentials directly, OAuth 2.0 is the recommended protocol. All API interactions with HelloSign are secured using HTTPS/TLS to encrypt data in transit, protecting against eavesdropping and tampering.

Understanding the appropriate authentication method is crucial for developing secure and functional integrations. HelloSign provides comprehensive documentation for both methods, detailing the steps for credential generation, token acquisition, and request signing, available in the HelloSign API documentation.

Supported authentication methods

HelloSign supports two primary authentication methods for its API:

• API Keys: A simple, token-based authentication method where a unique key is generated and used to authorize API requests. This method is generally suitable for server-to-server communication or applications where the API key can be securely stored and managed.
• OAuth 2.0: An open standard for access delegation, commonly used for web and mobile applications. OAuth 2.0 allows users to grant third-party applications limited access to their HelloSign account without exposing their credentials. This method is more complex to implement but provides enhanced security and flexibility for user-facing applications. The OAuth 2.0 specification is widely adopted across various platforms.

The table below summarizes the characteristics of each supported authentication method:

Getting your credentials

API Keys

To obtain an API Key for your HelloSign integration, follow these steps:

1. Log in to your HelloSign account.
2. Navigate to the API section within your settings or developer dashboard.
3. Generate a new API Key. HelloSign typically allows you to create multiple keys for different applications or environments (e.g., development, staging, production).
4. Copy the generated API Key. It is crucial to store this key securely, as it grants access to your HelloSign account's API capabilities. HelloSign will only show the full key once, so copy it immediately.

For detailed instructions, refer to the HelloSign API Key authentication guide.

OAuth 2.0

For OAuth 2.0 authentication, you will need to register your application with HelloSign to obtain a Client ID and Client Secret:

1. Log in to your HelloSign account and access the API section.
2. Register a new application, providing details such as the application name, description, and crucial redirect URIs. The redirect URI is where HelloSign will send the user back after they authorize your application.
3. Upon registration, HelloSign will provide you with a Client ID and a Client Secret. The Client Secret must be kept confidential as it authenticates your application to HelloSign.
4. Implement the OAuth 2.0 flow in your application, which typically involves directing users to HelloSign for authorization, receiving an authorization code, and then exchanging that code for an access token and refresh token using your Client ID and Client Secret.

The HelloSign OAuth 2.0 documentation provides step-by-step guidance on implementing the various OAuth 2.0 flows, including authorization code grant and refresh token usage.

Authenticated request example

This example demonstrates how to make an authenticated request using an API Key. For OAuth 2.0, the process involves obtaining an access token first and then including it in the Authorization header.

API Key example (Node.js)

Assuming you have your API Key stored securely, you can make a request to the HelloSign API. This example uses the axios library for HTTP requests.

const axios = require('axios');

const HELLOSIGN_API_KEY = 'YOUR_HELLOSIGN_API_KEY'; // Replace with your actual API Key

async function getAccountInfo() {
  try {
    const response = await axios.get('https://api.hellosign.com/v3/account',
      {
        auth: {
          username: HELLOSIGN_API_KEY,
          password: '' // API Keys use the username field, password is left empty
        },
        headers: {
          'User-Agent': 'HelloSign-Node-Example/1.0'
        }
      }
    );
    console.log('Account Info:', response.data);
  } catch (error) {
    console.error('Error fetching account info:', error.response ? error.response.data : error.message);
  }
}

getAccountInfo();

In this example, the API Key is passed using HTTP Basic Authentication, where the API Key serves as the username and the password field is left empty. HelloSign's API specifically supports this mechanism for API Key authentication, as detailed in their API Key authentication guide.

OAuth 2.0 example (Node.js - using access token)

After successfully completing the OAuth 2.0 flow and obtaining an access_token, subsequent API requests are made by including this token in the Authorization header as a Bearer token.

const axios = require('axios');

const ACCESS_TOKEN = 'YOUR_OBTAINED_ACCESS_TOKEN'; // Replace with your actual OAuth 2.0 access token

async function getAccountInfoOAuth() {
  try {
    const response = await axios.get('https://api.hellosign.com/v3/account',
      {
        headers: {
          'Authorization': `Bearer ${ACCESS_TOKEN}`,
          'User-Agent': 'HelloSign-Node-OAuth-Example/1.0'
        }
      }
    );
    console.log('Account Info (OAuth):', response.data);
  } catch (error) {
    console.error('Error fetching account info with OAuth:', error.response ? error.response.data : error.message);
  }
}

getAccountInfoOAuth();

Security best practices

Implementing authentication securely is critical for protecting sensitive data and maintaining the integrity of your HelloSign integrations. Adhere to these best practices:

• Keep API Keys and Client Secrets Confidential: Never hardcode API Keys or Client Secrets directly into your application's source code, especially for client-side applications. Store them in environment variables, secure configuration files, or a secrets management service. For client-side applications, always proxy API requests through your backend to prevent exposing credentials.
• Use HTTPS/TLS for All Communication: Ensure all API requests to HelloSign are made over HTTPS. HelloSign enforces this by default, but always verify your client is configured correctly. This encrypts data in transit, protecting against man-in-the-middle attacks. The IETF RFC 2818 details HTTP over TLS.
• Implement OAuth 2.0 Correctly: For user-facing applications, always use OAuth 2.0. Follow the recommended authorization flows (e.g., Authorization Code Grant for web apps) and securely manage refresh tokens to avoid repeated user logins. Validate redirect URIs and state parameters to prevent CSRF attacks.
• Regularly Rotate API Keys: Periodically generate new API Keys and revoke old ones. This minimizes the impact if a key is compromised. HelloSign's dashboard allows for easy key rotation.
• Limit API Key Permissions (if applicable): If HelloSign offers granular permissions for API Keys, configure them with the principle of least privilege. Grant only the necessary permissions for your application to function.
• Monitor API Usage: Keep an eye on your API usage patterns. Unusual spikes or activity could indicate a compromised key or unauthorized access.
• Secure Your Redirect URIs: For OAuth 2.0, ensure your registered redirect URIs are specific and secure. Avoid using broad wildcards, and always use HTTPS for redirect URIs.
• Handle Tokens Securely: Store OAuth 2.0 access and refresh tokens securely. Access tokens have a short lifespan, while refresh tokens can be used to obtain new access tokens. Protect refresh tokens with the same rigor as API Keys.
• Error Handling: Implement robust error handling for authentication failures. Provide informative but non-revealing error messages to users, and log detailed errors on your server for debugging.
• Understand Rate Limits: Be aware of HelloSign's API rate limits to prevent your application from being temporarily blocked. Implement exponential backoff and retry logic for rate limit errors.