Set up DocuSign signing with your own DocuSign app: step by step

1. Before you start

2. In DocuSign: create your integration key

Sign in to your DocuSign developer account and open eSignature Admin (Settings). DocuSign describes each setting on its app configuration page.

1. Open Apps and Keys and select Add App and Integration Key. Give it a name, for example AhlanHamad.
2. Under User Application, keep it set to Yes for “Is your application able to securely store a client secret?” (Authorization Code Grant, the default for new apps). DocuSign's consent link (section 3) needs this setting; you don't need to create a secret key, and AhlanHamad never uses one.
3. Under Service Integration, select Generate RSA. Copy the private key straight away, including the -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY----- lines, and keep it somewhere safe: DocuSign shows it only on this screen. You don't need the public key.
4. Under Additional settings → Redirect URIs, select Add URI and add one address, for example your company website. DocuSign requires a redirect URI for the consent link; after you accept, DocuSign opens that address and you can close the tab. AhlanHamad doesn't use it.
5. Save. Back on Apps and Keys, note four values: the Integration Key of your new app, your User ID, your API Account ID, and your account's base URI (in the developer environment, https://demo.docusign.net).

3. In DocuSign: grant consent once

JWT Grant lets AhlanHamad act as one DocuSign user, so that user has to accept it once (DocuSign: individual consent). AhlanHamad asks DocuSign for the signature and impersonation scopes.

1. Build the consent link: replace YOUR_INTEGRATION_KEY with your Integration Key and YOUR_REDIRECT_URI with the redirect URI you added in section 2, exactly as you saved it.
2. Developer (demo) account: https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id=YOUR_INTEGRATION_KEY&redirect_uri=YOUR_REDIRECT_URI
3. Sign in to DocuSign in your browser as the user whose User ID you will paste, open the link and select Accept.
4. DocuSign then opens your redirect URI. You can close that tab: consent is saved in DocuSign, and you don't have to do it again unless consent is withdrawn.

For a production account (after Go-Live, section 6) the link is the same on account.docusign.com: https://account.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id=YOUR_INTEGRATION_KEY&redirect_uri=YOUR_REDIRECT_URI. If your DocuSign organization has an administrator, they can grant consent for the organization's users instead (DocuSign: admin consent).

4. In AhlanHamad: connect your DocuSign app

Go to Integrations and open DocuSign. In the DocuSign Connection card, the first section is Connect with your own DocuSign app.

1. Integration Key: the Integration Key of your app.
2. User ID: the User ID of the DocuSign user who granted consent.
3. Account ID: your API Account ID.
4. RSA Private Key (PEM): paste the whole private key from section 2, including the BEGIN and END lines. “BEGIN RSA PRIVATE KEY” and “BEGIN PRIVATE KEY” both work.
5. REST Base URL: for the developer environment leave https://demo.docusign.net/restapi. For a production account, use your production account's base URI followed by /restapi.
6. Auth Server: for the developer environment leave account-d.docusign.com. For a production account, enter account.docusign.com (left empty, AhlanHamad uses account.docusign.com).
7. Click Connect to DocuSign.

AhlanHamad checks the key, asks DocuSign for an access token, confirms that the Account ID belongs to that DocuSign user, and from then on uses the base URI DocuSign reports for that account. When it works, the card says Connected to DocuSign and “Connected through your own app”, with your Account ID and REST Base URL. If DocuSign refuses, the message tells you what to fix (section 7).

5. Make DocuSign your signing provider

AhlanHamad checks every DocuSign status update with your own DocuSign Connect HMAC key (DocuSign: HMAC). Create one first.

1. In DocuSign eSignature Admin, open Connect, then Connect Keys, and select Add Secret Key. Copy the key when DocuSign shows it.
2. In AhlanHamad, on the DocuSign page, find the Signing provider card. Under Send signature requests with, choose DocuSign.
3. Paste the key into DocuSign Connect HMAC key. AhlanHamad stores it encrypted and never shows it again.
4. Click Save. The card then says “New signature requests go out from your DocuSign account. If DocuSign can't send one, it goes out with Ahlan Hamad e-signature and the sender is told.”
5. Click Send test envelope. It goes from your DocuSign account to the DocuSign user you connected as, and counts against your DocuSign plan like any envelope. Open the DocuSign email and sign it to see a complete envelope.

The card also shows the address under “DocuSign sends status updates for each envelope to:” (it ends in /webhooks/docusign). You don't need to create a Connect configuration for it: every envelope AhlanHamad sends carries its own status notification to that address, signed with your Connect keys. AhlanHamad re-reads each envelope from DocuSign before changing anything, and when everyone has signed it saves the signed PDF and DocuSign's certificate of completion.

6. Moving from the demo environment to production

A new integration key starts in DocuSign's developer (demo) environment, and envelopes sent there are not legally binding. To send real envelopes from your production DocuSign account, your key has to pass DocuSign's own Go-Live review. This review is between you and DocuSign, on your own integration key: AhlanHamad can't do it for you, but we are happy to help you prepare.

1. Use the key in the demo environment first: connect it, send the test envelope and a few real signature requests. DocuSign's review looks at the key's recent API activity in the demo environment.
2. In your developer account, start the key's Go-Live review (from Apps and Keys, or from DocuSign's newer Developer Console if that is where your key lives). DocuSign asks for an integration classification; it lists “Third-party integration key” for a partner product that needs your own key. If you're unsure which applies, ask DocuSign.
3. DocuSign requires a paid production account and an administrator of that account. When the review passes, promote the key to your production account. DocuSign copies the key with the same Integration Key value, but not its secrets or redirect URIs.
4. In your production account's Apps and Keys: add a redirect URI, select Generate RSA for a new private key, and note your production User ID, API Account ID and base URI.
5. Grant consent again, this time on account.docusign.com (section 3).
6. In AhlanHamad, click Disconnect DocuSign and connect again with the production values: Auth Server account.docusign.com and your production base URI followed by /restapi.
7. Add a Connect key in your production account (Connect → Connect Keys), paste it into DocuSign Connect HMAC key and Save: keys from your developer account don't work in production.

DocuSign explains the review on its Go-Live page and the production settings on After Go-Live.

7. If something goes wrong

8. Disconnecting

In the DocuSign Connection card, click Disconnect DocuSign, then Disconnect to confirm. As the dialog says: “New signature requests will go out with Ahlan Hamad e-signature. Envelopes already sent stay in DocuSign, but Ahlan Hamad can't update them or save their signed copies until you connect again. The saved DocuSign credentials are removed; your Connect key and your signing choice are kept.”

To stop the key working at DocuSign as well, remove its RSA keypair from your app in Apps and Keys.