PandaDoc Authentication: API Keys, OAuth 2.0, and Security

Authentication overview

PandaDoc provides mechanisms for securely authenticating applications and users to interact with its API. These mechanisms ensure that only authorized entities can access and manipulate documents, templates, and other resources within the PandaDoc platform. The choice of authentication method depends on the integration's nature: server-side applications typically use API keys, while client-side or user-facing applications leverage OAuth 2.0 to manage user permissions without exposing credentials.

Proper authentication is fundamental for maintaining the integrity and confidentiality of sensitive document workflows, especially in regulated industries where compliance standards like SOC 2 Type II and GDPR are critical. PandaDoc's approach to authentication aligns with industry best practices to protect data and control access to its services. For detailed guidance, developers should consult the official PandaDoc API documentation.

Supported authentication methods

PandaDoc supports two primary authentication methods to accommodate different integration scenarios:

• API Key Authentication: This method is suitable for server-to-server integrations where an application needs to access PandaDoc resources directly without user intervention. API keys are long-lived tokens that grant broad access to an account's resources.
• OAuth 2.0: This protocol is designed for applications that need to access a user's PandaDoc account on their behalf. OAuth 2.0 enables third-party applications to obtain limited access to a user's resources without requiring their credentials. It is the recommended method for applications that interact with user-specific data or require user consent for access.

Comparison of Authentication Methods

The choice between API Key and OAuth 2.0 depends on the application's architecture and security requirements. For automated processes that operate independently of a specific user session, API keys offer simplicity. For applications that serve individual users and require their explicit permission, OAuth 2.0 provides a more secure and flexible framework, aligning with modern authorization standards as described by The OAuth 2.0 Authorization Framework.

Getting your credentials

To authenticate with the PandaDoc API, you will need to obtain the appropriate credentials based on your chosen authentication method.

For API Key Authentication:

1. Log in to your PandaDoc account.
2. Navigate to the 'Developers' section or 'Integrations' settings within your account.
3. Locate the 'API Keys' tab.
4. Generate a new API key. Ensure you copy and store this key securely, as it will not be displayed again.

PandaDoc API keys are typically associated with your account and grant access permissions defined by your account's role. Treat your API key like a password, as it provides direct access to your PandaDoc resources. For detailed steps on generating and managing API keys, refer to the PandaDoc help documentation.

For OAuth 2.0:

1. Log in to your PandaDoc account.
2. Access the 'Developers' or 'Integrations' section.
3. Register a new application. During registration, you will need to provide details such as your application's name, description, and importantly, the redirect URI(s). The redirect URI is where PandaDoc will send the user back after they authorize your application.
4. Upon successful registration, PandaDoc will provide you with a Client ID and a Client Secret. Store these credentials securely.
5. Configure your application to initiate the OAuth 2.0 flow, which involves redirecting the user to PandaDoc's authorization endpoint, handling the authorization code, and exchanging it for an access token.

The OAuth 2.0 flow is more complex than API key usage but offers enhanced security and user control. Developers should familiarize themselves with the standard OAuth 2.0 grant types, particularly the Authorization Code Grant, which is commonly used for web applications. The IETF RFC 6749 provides the technical specification for OAuth 2.0.

Authenticated request example

Once you have obtained your credentials, you can make authenticated requests to the PandaDoc API. The following examples demonstrate how to include your authentication token in an API request.

API Key Authentication Example (Python)

This Python example uses the requests library to make a simple GET request to retrieve a list of documents, authenticating with an API key.

import requests

API_KEY = "YOUR_PANDADOC_API_KEY"
BASE_URL = "https://api.pandadoc.com/public/v1"

headers = {
    "Authorization": f"API-Key {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.get(f"{BASE_URL}/documents", headers=headers)

if response.status_code == 200:
    print("Successfully retrieved documents:")
    print(response.json())
else:
    print(f"Error: {response.status_code} - {response.text}")

OAuth 2.0 Authentication Example (Node.js)

This Node.js example demonstrates how to use an obtained access token to make an authenticated request. It assumes you have already completed the OAuth 2.0 authorization flow and possess a valid access token.

const fetch = require('node-fetch');

const ACCESS_TOKEN = 'YOUR_PANDADOC_ACCESS_TOKEN';
const BASE_URL = 'https://api.pandadoc.com/public/v1';

async function getDocuments() {
  try {
    const response = await fetch(`${BASE_URL}/documents`, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${ACCESS_TOKEN}`,
        'Content-Type': 'application/json'
      }
    });

    if (response.ok) {
      const data = await response.json();
      console.log('Successfully retrieved documents:');
      console.log(data);
    } else {
      const errorText = await response.text();
      console.error(`Error: ${response.status} - ${errorText}`);
    }
  } catch (error) {
    console.error('Fetch error:', error);
  }
}

getDocuments();

In both examples, the authentication token (API key or access token) is included in the Authorization header of the HTTP request. For API keys, the scheme is API-Key, and for OAuth 2.0 access tokens, it's Bearer. Always ensure your tokens are transmitted over HTTPS to prevent eavesdropping.

Security best practices

Implementing strong security practices for authentication is crucial when integrating with PandaDoc, especially given the sensitive nature of document management. Adhering to these guidelines helps protect your application and user data:

• Secure Credential Storage: Never hardcode API keys or client secrets directly into your application's source code. Store them in environment variables, secure configuration files, or a dedicated secret management service (e.g., AWS Secrets Manager, Google Secret Manager, Azure Key Vault).
• Use HTTPS/TLS: Always ensure all API communications are conducted over HTTPS (TLS). This encrypts data in transit, protecting credentials and sensitive document content from interception. PandaDoc's API endpoints enforce HTTPS.
• Least Privilege Principle: Grant only the necessary permissions to your API keys or OAuth 2.0 applications. Avoid using credentials with overly broad access if a more restricted scope is sufficient for your application's functionality.
• Rotate API Keys: Regularly rotate your API keys (e.g., every 90 days). If an API key is compromised, rotating it limits the window of exposure. Implement a process to generate new keys and update your applications.
• OAuth 2.0 Best Practices: For OAuth 2.0, follow the recommended security practices:
• Use the Authorization Code Grant flow for web applications.
• Implement PKCE (Proof Key for Code Exchange) for public clients (e.g., mobile or desktop apps) to prevent authorization code interception attacks.
• Validate the state parameter during the OAuth 2.0 flow to prevent Cross-Site Request Forgery (CSRF) attacks.
• Store refresh tokens securely and revoke them if suspicious activity is detected.
• Error Handling: Implement robust error handling for authentication failures. Avoid providing overly descriptive error messages that could leak sensitive information about your authentication setup.
• Logging and Monitoring: Monitor API access logs for unusual patterns, repeated failed authentication attempts, or access from unexpected IP addresses. Implement alerts for potential security incidents.
• Rate Limiting: Be aware of and respect PandaDoc's API rate limits to avoid being blocked. Excessive requests, especially failed authentication attempts, can trigger security measures.
• Keep SDKs and Libraries Updated: Use the latest versions of PandaDoc's official SDKs and any third-party libraries used for authentication (e.g., OAuth libraries). Updates often include security patches and improvements. PandaDoc provides SDKs for Python, Node.js, Ruby, PHP, .NET, and Java.
• Regular Security Audits: Periodically review your authentication implementation and overall application security to identify and address potential vulnerabilities.