> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # Using the Docusign API Postman collections > Docusign Postman collections enable you to execute requests against the Docusign REST APIs quickly and easily inside Postman. ## Using the Docusign API Postman collections Follow this guide to install and configure the Docusign API Postman collections, which enable you to execute requests against the [Docusign APIs](/docs) quickly and easily inside [Postman](https://www.postman.com). The Docusign API Postman collections include examples for common workflows such as authenticating to retrieve your account ID and base URI, sending an envelope via email, creating reusable templates, and signing documents directly through your app or website, also known as *embedded signing*. ## Prerequisites To set up the Docusign API Postman collections on your system, you need: * A Docusign developer account. You can [create an account](https://www.docusign.com/developers/sandbox) for free at the [Developer Center](/). * A Postman account. You can create an account on [postman.com](http://postman.com). ## Step 1: Create your environment The **Set Up Your Environment** button below opens a dialog box prompting you to configure your Postman environment using the values in [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page. Any app you create with Docusign is called an *integration.* 1. Open [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page of your Docusign account. 2. **Integration Key(IK):** All your integrations are identified in your Docusign developer account by their *integration key,* which is a [GUID](http://guid.one/) issued to your integration. To add an app and get an integration key, 1. Select **Add App and Integration Key.** 2. Enter a name for the app and select **Create App**. 3. In the integration page, under the **General Info**, copy the **Integration Key** value, which is automatically generated when you select **Create App.** 3. **Corresponding secret key:** For [Authorization Code Grant](/platform/auth/authcode), your integration needs a secret key as well. To add a secret key, 1. Under the **Authentication** section, Select + **Add Secret Key**. 2. Copy and save your secret key now because it won't be shown again. If lost, you must generate a new one. 3. Select **Save**. Select **Add Secret Key** on the **Apps and Keys** page and copy the value; you can only do this when you create the key, as it won't be visible thereafter. Now, to create your Postman environment, select **Setup Your Environment** button below. 1) Enter the **Integration key** value. 2) Enter the **Corresponding secret key** value. 3) Select **Environment** as **Demo**. 4) Select **API version** as **v2.1.** 5) Select **Close**. The Postman collection supports the eSignature REST API versions v2 and v2.1. Select **v2.1**, which is preferred. v2 will be deprecated in the future. ## Step 2: Import into Postman Before you select one of the options below, be sure to log in to Postman from the Postman UI in your browser. Select a button below to import the Docusign Postman collection for that API and your environment variables into your installation of Postman. To import a Postman collection, 1. Select **Run in Postman**. 2. Select **Fork Collection**. 3. Enter a **Fork label**. 4. Select a **Workspace**. 5. Select **Fork collection**. > **Note:** Your environment variables are added while importing the Postman collection. If you want to import more than one collection, refresh the page between imports to avoid caching issues. | API Name | Postman Collections URL | | ------------------------- | ----------------------- | | **eSignature REST API** | | | **Web Forms API** | | | **Maestro API** | | | **Agreement Manager API** | | | **Workspaces API (Beta)** | | | **Rooms API** | | | **Click API** | | | **Docusign Admin API** | | | **Monitor API** | | | **Notary API** | | ## Step 3: Pick your desired OAuth grant type Every request to any Docusign API requires that you authenticate with Docusign by presenting an access token. To execute any API request in Postman, you need to such a token for you. Docusign uses the [OAuth](https://www.oauth.net) authentication model; visit our [Authenticate](/platform/auth) guide to see how it works and determine which type to use for your integration. Each Postman collection's **🔐 Quick Auth Setup → Then Run APIs** folder contains requests for three OAuth 2.0 workflows, one Refresh Access Token, and one user info flow. * 01 - JWT / Service Integration, see [JSON Web Token (JWT) Grant](/platform/auth/jwt). * 02 - Authorization Code Grant (Confidential Client), see [Authorization Code Grant](/platform/auth/authcode). * 03 - Authorization Code Grant with PKCE (Public Client) , see[Proof Key for Code Exchange (PKCE)](/platform/auth/authcode#public-authorization-code-grant). * 04 - Refresh Access Token. Used to refresh the generated access token after its expiry. * 05 - User Info. This request is for finding and storing your account ID and base URI. Note that you need to [obtain consent](/platform/auth/consent) through the web interface the first time you request access via the API. ## Authentication Type #### JSON Web Token Grant (JWT) To set up a JSON Web Token (JWT) grant, copy the following parameter values from [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page and paste in the corresponding variables of your Postman Environment. Before saving the variables in Postman, select **Pin to collection** for the **Docusign-account-d** environment. ![postman environment](/_fern-files/_img/f3422d83f1e36e49a0211b27e5e694db9410de6af31e18b9f0bc1169e88bb9e1.webp) | Field Name in Apps and Keys Page | Variable Name in Postman Collection | Description | | ---------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **General Info > Integration Key** | integrationKey | An integration key identifies your integration and links to its configuration values. Refer [Create an integration key.](/platform/configure-app#how-to-get-an-integration-key). | | **Additional Settings > Redirect URIs** | redirectUri | The redirect URI is the URI (URL) to which Docusign will redirect the browser after authentication. Refer [Set a redirect URI.](/platform/configure-app#how-to-set-a-redirect-uri). | | **Service Integration > RSA Keypairs (ID)** | privateKey | Refer [RSA key pair](/platform/configure-app#rsa-key-pair). | | **Apps and Keys > My Account Information > User ID** | userId | Find your [User ID](/platform/configure-app#user-id) in the Apps and Keys page. | 1. Go to 🔐 **Quick Auth Setup -> Then Run APIs > 01 - JWT / Service Integration >** then **01-1 - Construct Consent URL (JWT)** and send a request to generate authorization URL. 2. Paste the **authorizeUrl** into your web browser’s address bar, and open the page. 3. Select **Allow Access**. (Sign in to your Docusign Developer’s account if required). Once you give your consent to the requested scopes, the browser will redirect to your redirect URI. 4. Execute the **01-2 - JWT Token (exchange)** request to generate an access token. 5. Execute the **05 Get User Info** request to retrieve your account ID and base URI; These values will be added to your environmental variables, so they’re ready for subsequent requests. If you get an internal error, select the Authorization of **05 Get User Info** in Postman Authorization tab as **Bearer Token** and paste the access token obtained in Step 4. #### Authorization Code Grant To set up an authorization code grant , copy the following parameter values from [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page and paste in the corresponding variables of your Postman Environment. Before saving the variables in Postman, select **Pin to collection** for the **Docusign-account-d** environment. ![postman environment](/_fern-files/_img/f3422d83f1e36e49a0211b27e5e694db9410de6af31e18b9f0bc1169e88bb9e1.webp) | Field Name in Apps and Keys Page | Variable Name in Postman Collection | Description | | --------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **General Info > Integration Key** | integrationKey | An integration key identifies your integration and links to its configuration values. Refer [Create an integration key.](/platform/configure-app#how-to-get-an-integration-key). | | **Authentication > Secret Key** | clientSecret | The secret key identifies your integration app through a unique key. Refer [secret key](/platform/configure-app#secret-key). | | **Additional Settings > Redirect URIs** | redirectUri | The redirect URI is the URI (URL) to which Docusign will redirect the browser after authentication. Refer [Set a redirect URI.](/platform/configure-app#how-to-set-a-redirect-uri) | 1. Go to 🔐 **Quick Auth Setup -> Then Run APIs > 02 – Authorization Code Grant (Confidential Client)** **>** then **02-1 – Construct Authorization URL** and send a request to generate authorization URL. 2. Paste the **authorizeUrl** into your web browser’s address bar, and open the page. 3. Select **Allow Access**. (Sign in to your Docusign Developer’s account if required). Once you give your consent to the requested scopes, the browser will redirect to your redirect URI with a long string returned for the **code** parameter embedded in the URL. 4. Copy this **code** value ( Note: The **code** value is valid only for one minute. If the code is expired, refresh the URL displayed in Step 2 and obtain a new code). 5. Go to 🔐 **Quick Auth Setup -> Then Run APIs > 02 – Authorization Code Grant (Confidential Client) > 02-2 – Exchange Authorization Code for Tokens** request. Paste the value of the **code** parameter into the code value under **Body** of the request. Alternatively, you can save the code in the Postman variable **authCodeNoPkce**. 6. Execute the **02-2 – Exchange Authorization Code for Tokens** request to generate an access token and a refresh token. The access token is saved in the Postman variable to be used for subsequent API calls. 1. If you receive an **expired_client_token** error in the response, too much time has elapsed since you obtained the code from the [https://account-d.docusign.com/oauth/auth](https://account-d.docusign.com/oauth/auth) URL. 2. Repeat the steps from Step 2 to generate a new code and obtain the access token. 7. Execute the **05 Get User Info** request to retrieve your account ID and base URI; These values will be added to your environmental variables, so they’re ready for subsequent requests. If you get an internal error, select the Authorization of **05 Get User Info** in Postman Authorization tab as **Bearer Token** and paste the access token obtained in Step 4. #### Public Authorization Code Grant To set up an public authorization code grant, copy the following parameter values from [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page and paste in the corresponding variables of your Postman Environment. Before saving the variables in Postman, select **Pin to collection** for the **Docusign-account-d** environment. ![postman environment](/_fern-files/_img/f3422d83f1e36e49a0211b27e5e694db9410de6af31e18b9f0bc1169e88bb9e1.webp) | Field Name in Apps and Keys Page | Variable Name in Postman Collection | Description | | ------------------------------------------------------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **General Info > Integration Key** | integrationKey | An integration key identifies your integration and links to its configuration values. Refer [Create an integration key.](/platform/configure-app#how-to-get-an-integration-key). | | **Additional Settings > Redirect URIs** | redirectUri | The redirect URI is the URI (URL) to which Docusign will redirect the browser after authentication. Refer [Set a redirect URI.](/platform/configure-app#how-to-set-a-redirect-uri) | | **Authentication > User Application** | Not applicable | Refer [set the authentication method](/platform/configure-app#authentication-method). 1. Select **No** for **Is your application able to securely store a client secret?** 2\*\*.\*\* Select **Single-Page Web Application** for **App Type**. 3. Select **Authorization Code Grant with Proof Key for Code Exchange (PKCE)** for **Authentication Method for your App**. | | **Additional Settings > Origin URLs** and **Allowed HTTP Methods** | originUrl | Refer [CORS configuration parameters](/platform/configure-app#cors-configuration) 1. Add the list of Origin URL by selecting **+ Add Origin URL** in [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page. 2. Add these urls in Postman variable **originUrl** as common separated values. 3. Select **Allow CORS for OAuth calls** checkbox. 4. Select all checkboxes of **Allowed HTTP methods** such as **GET, POST, PUT, DELETE,** and **HEAD**. 5. Select **Save**. | 1. Go to 🔐 **Quick Auth Setup -> Then Run APIs > 03 - Authorization Code Grant with PKCE (Public Client) >** then **03-1 - Construct Authorization URL with PKCE** and send a request to generate authorization url. 2. Paste the **authorizeUrl** into your web browser’s address bar, and open the page. 3. Select **Allow Access**. (Sign in to your Docusign Developer’s account if required). Once you give your consent to the requested scopes, the browser will redirect to your redirect URI with a long string returned for the **code** parameter embedded in the URL. 4. Copy this **code** value ( Note: The **code** value is valid only for one minute. If the code is expired, refresh the URL displayed in Step 2 and obtain a new code). 5. Go to 🔐 **Quick Auth Setup -> Then Run APIs > 03 - Authorization Code Grant with PKCE (Public Client) > 03-2 - Exchange Authorization Code for Tokens (PKCE)** request. Paste the value of the **code** parameter into the code value under **Body** of the request. Alternatively, you can save the code in the Postman variable **authCodePkce**. 6. Execute the **03-2 - Exchange Authorization Code for Tokens (PKCE)** request to generate an access token and a refresh token. 1. If you receive an **expired_client_token** error in the response, too much time has elapsed since you obtained the code from the [https://account-d.docusign.com/oauth/auth](https://account-d.docusign.com/oauth/auth) URL. 2. Repeat the steps from Step 2 to generate a new code and obtain the access token. 7. Execute the **05 Get User Info** request to retrieve your account ID and base URI; These values will be added to your environmental variables, so they’re ready for subsequent requests. If you get an internal error, select the Authorization of **05 Get User Info** in Postman Authorization tab as **Bearer Token** and paste the access token obtained in Step 4. ### Using access tokens and account IDs Nearly every Docusign API call requires an authorization header containing your access token: **Authorization**: `Bearer {{accessToken}}` **Access Token Lifespans & Renewal** * **Authorization Code Grant:** * **Access Token Duration:** 8 hours. * **Renewal:** Use a refresh token to generate a new access token via the **04 Refresh Access Token** request. Refresh tokens remain valid for up to **30 days**. * **JSON Web Token (JWT) Grant:** * **Access Token Duration:** 1 hour. * **Renewal:** Refresh tokens are not supported. To renew, re-run the **02-2 - Exchange Authorization Code for Tokens** request (or generate a new JWT assertion). **User & Account Identification** * **Account ID Requirement:** Many API endpoints require a specific accountId. * **Retrieval:** Obtain your account ID by executing the **05 Get User Info** request or see in your [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page at **Apps and Keys > My Account Information > User ID.** ### Requests in the Examples folder Please add and define the following variables if you're planning to run the Postman requests under the Examples folder: * user_email = [email@domain.com](mailto:email@domain.com) * user_name = Foo Bar ## Step 4: Test production credentials After you [enable an integration key in production](/docs/esign-rest-api/go-live), you can test it using your production integration key and secret. Simply change the `hostenv` environment variable to **account.docusign.com** and re-authenticate using the **Authentication** examples to get your new base URI.