Creating a private key in DocuSign is an essential step when setting up an application integration, particularly for authentication methods like JSON Web Token (JWT) Grant. This process involves creating an application within your DocuSign account and then generating the necessary cryptographic keys.
Setting Up Your DocuSign Application and Generating Keys
To create a private key for your DocuSign integration, you'll follow a structured process within your DocuSign account, which involves setting up an application and choosing the appropriate authentication method.
-
Navigate to Apps and Keys:
- Log in to your DocuSign developer account (or production account, if applicable).
- From the Accounts view, select Apps and Keys. This section is your central hub for managing all your API integrations.
-
Add a New App and Integration Key:
- Click on Add App and Integration Key. This initiates the creation of a new application profile.
-
Name and Create Your App:
- Enter a descriptive name for your application. This name helps you identify the integration later.
- Select Create App. DocuSign will generate an Integration Key (also known as a Client ID) for your application. This key uniquely identifies your application to DocuSign's API.
-
Select Authentication Type and Generate Keys:
- After creating the app, you will need to select an authentication type. The choice here dictates whether you'll generate a "secret key" or a "key pair" (which includes your private key).
- For methods requiring a private key, such as JWT Grant:
- Choose JWT Grant as your authentication method.
- Follow the prompts to generate a key pair. This process typically involves DocuSign generating a unique public/private key pair for your application.
- Crucially, you will be prompted to download your private key. This is a one-time download, so ensure you save it securely. The corresponding public key will be registered with DocuSign automatically.
Understanding DocuSign Authentication Keys
DocuSign supports different authentication flows, each with distinct key requirements. Understanding these helps clarify where a "private key" fits in.
-
JWT Grant Authentication:
- Key Type: Requires a key pair (public and private keys).
- Purpose: The private key is used by your application to digitally sign a JWT assertion, proving its identity to DocuSign without requiring user interaction for subsequent calls. The public key is registered with DocuSign to verify the signature.
- When to use: Ideal for service integrations where your application needs to make API calls on behalf of a user or system without constant user login.
-
Authorization Code Grant Authentication:
- Key Type: Requires a Client Secret.
- Purpose: The client secret (which functions like a password for your application) is used in conjunction with the Integration Key to obtain access tokens after a user has granted consent.
- When to use: Suitable for web applications where users interact with your application and provide consent to access their DocuSign account.
The following table summarizes the key types commonly used in DocuSign API authentication:
| DocuSign Authentication Type | Key Generated | Primary Use Case |
|---|---|---|
| JWT Grant | Key Pair (Public/Private Key) | Server-to-server communication, API calls on behalf of users without requiring direct user interaction. |
| Authorization Code Grant | Client Secret | Web applications where users grant consent to access their DocuSign account. |
Best Practices for Handling Your Private Key
Your private key is critical for the security of your DocuSign integration. Treat it with the utmost care:
- Secure Storage: Store your private key in a highly secure location. Never expose it in client-side code, public repositories, or unsecured environments. Consider using secure key management services, environment variables, or encrypted storage.
- Access Control: Restrict access to the private key to only the necessary personnel and systems.
- Rotation: While not always strictly required for private keys used with JWT, consider implementing a key rotation strategy if your security policies demand it. You can generate new key pairs in DocuSign and update your application.
- Backup: Create secure, encrypted backups of your private key. Loss of the private key will render your JWT integration inoperable until a new key pair is generated and configured.
By following these steps and best practices, you can effectively create and manage the private keys necessary for secure DocuSign API integrations.
