> 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 # How to share access to an individual envelope > This topic demonstrates how to share a single envelope with another user and view it through the Shared Access feature without being a recipient of the envelope. eSignature REST API 2.1 only This topic demonstrates how to share a single envelope with another user and view it through the Shared Access feature without being a recipient of the envelope. The Shared Access feature enables a user (the *principal*) to grant another user (the *agent*) access to an existing principal's envelope. **Important**: There must be envelopes in the principal's inbox to complete this how-to. See [How to request a signature by email](/docs/esign-rest-api/how-to/request-signature-email-remote) to learn more about creating an envelope. See [Shared Access](/docs/esign-rest-api/esign101/concepts/envelopes/share-access-to-mailbox-or-envelopes) for details on the feature and the list of supported envelope actions. > **Note** > > Run this code example from our [Quickstart](/docs/esign-rest-api/quickstart) or launcher projects: [Bash](https://github.com/docusign/code-examples-bash), [C#](https://github.com/docusign/code-examples-csharp), [Java](https://github.com/docusign/code-examples-java), [Node.js](https://github.com/docusign/code-examples-node), [PHP](https://github.com/docusign/code-examples-php), [PowerShell](https://github.com/docusign/code-examples-powershell), [Python](https://github.com/docusign/code-examples-python), or [Ruby](https://github.com/docusign/code-examples-ruby). ## Required data Running the code in this how-to requires this data: | Data element | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | \{ACTIVATION_CODE} | A string value, 50 characters or less, that you provide to the agent to activate their account. This string must not contain the symbols \<, >, &, and #. Save this code; the agent needs it to activate. | | \{AGENT_EMAIL} | A string value for the email address of the new agent user. The agent receives an activation email at this address. | | \{AGENT_NAME} | A string value for the full name of the new agent user. | | \{AGENT_USER_ID} | A [GUID](http://guid.one/) value that identifies the agent user. This value is automatically generated by Docusign. It is returned when you create the agent in Step 3. | | \{API_ACCOUNT_ID} | A [GUID](http://guid.one/) value that identifies your account. This value is automatically generated by Docusign for any account you create. Copy the value from the **API Account ID** field on the [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page. | | \{BASE_PATH} | A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at https\://\/restapi Where \ is demo.docusign.net for the developer environment and is the result of the GetUserInfo call in production. | | \{ENVELOPE_ID} | A [GUID](http://guid.one/) value that identifies the envelope to share. You can get it from the response of the [Send an envelope](/docs/esign-rest-api/how-to/request-signature-email-remote) example. | ## Step 1. Obtain your OAuth token To make the API calls shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario. > **Note** > > See [Confidential Authorization Code Grant](/platform/auth/authcode#confidential-authorization-code-grant) for guidance on your options to get a Confidential Authorization Code Grant OAuth token. ![Three icons that represent the three methods a user can use to obtain an OAuth token: JSON Web Token (JWT), Public Authorization Code Grant (ACG), and Confidential Authorization Code grant](/_fern-files/_img/64f473773042ee439449a096bf7673292b1585b86a4ccc55f82ba0dda41f61a1.webp) ## Step 2. Construct your API headers After you have a valid OAuth access token, you are ready to construct the API headers that you will pass to the API call. Construct your headers like this, but make sure to substitute your valid OAuth access token for \{ACCESS_TOKEN}. **`Bash`** ```bash title="Bash" declare -a Headers=('--header' "Authorization: Bearer ${ACCESS_TOKEN}" '--header' "Accept: application/json" '--header' "Content-Type: application/json") ``` **`PowerShell`** ```text title="PowerShell" $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]" $headers.add("Authorization", "Bearer $accessToken") $headers.add("Content-Type", "application/json") ``` ## Step 3. Construct the request body to create an agent and call the API To share an envelope with an agent, there must be at least two users in the principal's account. This step creates a new agent with whom the envelope will be shared. If there is already a second user in the principal's account, you can skip this step and instead record the second user's user ID to use in the next step. First, create the request body for the API call to create an agent. Set the `userName` and `email` fields to the name and email address associated with the agent. Set the `activationAccessCode` to a string that the agent will use to activate their account. Make a POST request to the [Users:create](/docs/esign-rest-api/reference/users/users/create) endpoint and include the request body to create the agent. Then, extract the agent's `userId` from the response as \{AGENT_USER_ID}. You will use it again in Step 4. After the agent is created, Docusign sends an activation email to the agent's address. Open the email and activate the agent by using the activation code that you provided before you continue to the next step. **`Bash`** ```bash title="Bash" printf \ '{ "newUsers": [ { "activationAccessCode": "'"${ACTIVATION}"'", "userName": "'"${AGENT_NAME}"'", "email": "'"${AGENT_EMAIL}"'" } ] }' >> $request_data Status=$(curl --request POST ${base_path}/v2.1/accounts/${ACCOUNT_ID}/users \ "${Headers[@]}" \ --data-binary @${request_data} \ --output ${response}) echo "" echo "Response: " cat $response echo "" AGENT_USER_ID=`cat $response | grep userId | sed 's/.*\"userId\":\"//' | sed 's/\",.*//'` ``` **`PowerShell`** ```text title="PowerShell" @{ newUsers = @( @{ activationAccessCode = $activation; userName = $agentName; email = $agentEmail; }; ); } | ConvertTo-Json -Depth 32 > $requestData Invoke-RestMethod ` -Uri "${apiUri}/v2.1/accounts/${accountId}/users" ` -Method 'POST' ` -Headers $headers ` -InFile (Resolve-Path $requestData).Path ` -OutFile $response $agentUserId = $(Get-Content $response | ConvertFrom-Json).newUsers.userId ``` ## Step 4. Construct the request body to share the envelope and call the API This step shares the principal's envelope with the agent created in the previous step. If you already have a second user with whom you'd like to share the envelope, you can provide their user ID in the `agentUser` JSON. Now that you have created and activated an agent, you need to authorize the agent to manage the envelope. In the `shares` array, set the `userId` field of `agentUser` to the one associated with the agent and the `accountId` field to the principal's API account ID. Set the `permission` to `manage`. You can also set a `customMessage` for the agent. Make a POST request to the [Envelopes:createShares](/docs/esign-rest-api/reference/envelopes/envelopes/createshares) endpoint and include the request body to share the envelope. Use the ID of the envelope to share as \{ENVELOPE_ID} and the principal's API account ID as \{API_ACCOUNT_ID} in the call. Only the envelope that you specify is shared. The agent does not get access to the rest of the principal's envelopes. **`Bash`** ```bash title="Bash" printf \ '{ "shares": [ { "agentUser": { "userId": "'"${AGENT_USER_ID}"'", "accountId": "'"${ACCOUNT_ID}"'" }, "permission": "manage", "customMessage": "This envelope is shared with you." } ] }' >> $request_data Status=$(curl --request POST ${base_path}/v2.1/accounts/${ACCOUNT_ID}/envelopes/${ENVELOPE_ID}/shares \ "${Headers[@]}" \ --data-binary @${request_data} \ --output ${response}) ``` **`PowerShell`** ```text title="PowerShell" $body = @{ shares = @( @{ agentUser = @{ userId = $agentUserId; accountId = $accountId; }; permission = "manage"; customMessage = "This envelope is shared with you."; }; ); } | ConvertTo-Json -Depth 32 Invoke-RestMethod ` -Uri "${apiUri}/v2.1/accounts/${accountId}/envelopes/${envelopeId}/shares" ` -Method 'POST' ` -Headers $headers ` -Body $body ` -OutFile $response ``` ## Step 5. Retrieve the shared envelopes as the agent The following API call will be made by the agent. Before making this API call, you need to authenticate as the agent. After you have authenticated as the agent, retrieve the envelopes that are shared with the agent by calling the [Envelopes:getSharedEnvelopes](/docs/esign-rest-api/reference/envelopes/envelopes/getsharedenvelopes) endpoint. Any API calls made on behalf of the principal need to include the `X-DocuSign-Act-On-Behalf` header and substitute the principal's user ID for \{IMPERSONATION_USER_GUID}. Be sure to also substitute the API account ID of the agent for \{ACCOUNT_ID}. The example limits the results to envelopes from the last 10 days. **`Bash`** ```bash title="Bash" response=$(mktemp /tmp/response-bs.XXXXXX) if date -v -10d &> /dev/null ; then # Mac from_date=`date -v -10d '+%Y-%m-%dT%H:%M:%S%z'` else # Not a Mac from_date=`date --date='-10 days' '+%Y-%m-%dT%H:%M:%S%z'` fi curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \ --header "X-DocuSign-Act-On-Behalf: ${IMPERSONATION_USER_GUID}" \ --header "Content-Type: application/json" \ --get \ --output $response \ --data-urlencode "from_date=${from_date}" \ --request GET ${base_path}/v2.1/accounts/${ACCOUNT_ID}/envelopes/shared/ ``` **`PowerShell`** ```text title="PowerShell" try { $fromDate = ((Get-Date).AddDays(-10d)).ToString("yyyy-MM-ddThh:mm:ssK") $response = New-TemporaryFile Invoke-RestMethod ` -Uri "${apiUri}/v2.1/accounts/${accountId}/envelopes/shared" ` -Method 'GET' ` -Headers @{ 'Authorization' = "Bearer $accessToken"; 'Content-Type' = "application/json"; } ` -Body @{ "from_date" = ${fromDate} } ` -OutFile $response if ([string]::IsNullOrEmpty((Get-Content $response -Raw))) { Write-Output "" Write-Output "Response body is empty because no envelopes have been shared with the agent." } else { Write-Output "" Write-Output "Response:" Write-Output "" Get-Content $response } ``` ## Expected response If you run this code example from our Quickstart or launcher projects, you should see a JSON response of the envelopes shared with the agent's account. **`Sample response`** ```json title="Sample response" { "resultSetSize": "1", "startPosition": "0", "endPosition": "0", "totalSetSize": "1", "envelopes": [ { "status": "sent", "documentsUri": "/envelopes/e63fd3e2-xxxx-xxxx-xxxx-5a73e59c7f9d/documents", "recipientsUri": "/envelopes/e63fd3e2-xxxx-xxxx-xxxx-5a73e59c7f9d/recipients", "envelopeUri": "/envelopes/e63fd3e2-xxxx-xxxx-xxxx-5a73e59c7f9d", "emailSubject": "Please sign this document set", "envelopeId": "e63fd3e2-xxxx-xxxx-xxxx-5a73e59c7f9d", "signingLocation": "online", "createdDateTime": "2026-10-12T01:09:04.2170000Z", "lastModifiedDateTime": "2026-10-12T01:09:04.2330000Z", "sentDateTime": "2026-10-12T01:09:05.5600000Z", "statusChangedDateTime": "2026-10-12T01:09:05.5600000Z", "purgeState": "unpurged", "envelopeIdStamping": "true", "isSignatureProviderEnvelope": "false" } ] } ``` ## Next steps * Run this code example from our [Quickstart](/docs/esign-rest-api/quickstart) or launcher projects: [Bash](https://github.com/docusign/code-examples-bash) or [PowerShell](https://github.com/docusign/code-examples-powershell). * Learn more about [How to share access to a Docusign envelope inbox](/docs/esign-rest-api/how-to/shared-access). * See how to [Go-Live](/docs/esign-rest-api/go-live) with a completed app and find the base path for API calls in the production environment.