> 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

# Pre-Docusign Operations & Request Recipient Token

## Creating the envelope

Creating envelops for Embedded Recipients parallels the Remote Recipient model. But sender needs to specify if the recipient is Remote or Embedded. Sender can do this by using ClientUserId. A non-null ClientUserId implies that user is Embedded. A single envelope can contain both Embedded and Remote Recipients.

## Requesting Recipient Tokens (RequestRecipientToken and RequestRecipientFaxToken)

Docusign constrains access to the Embedded signature process via short-lived Recipient Tokens. Successful token requests return an URL that will invoke the Docusign signing wizard for a particular envelope and Embedded Recipient. Envelopes must be sent before a recipient token can be requested (recipient tokens will not work with draft envelopes).

> **Important:** iFrames should not be used for embedded operations on mobile devices due to screen space issues. For iOS devices Docusign recommends using a WebView.

There are two types of recipient tokens available:

* RequestRecipientToken: This token returns a URL to invoke a Docusign signing session where the signer completes the signing process online.
* RequestRecipientFaxToken: This token returns a URL to invoke a Docusign signing session where the signer is required to print out and sign documents. The documents are then returned to Docusign by fax or upload.> **Note:** An alternative to using RequestRecipientFaxToken is to use RequestRecipientFaxPDF to return a PDF version of a fax cover page and documents in an envelope rather than returning a URL for a signing session. For more information about this option see [RequestRecipientFaxPDF](/docs/esign-soap-api/reference/embedding-group/requestrecipientfaxpdf).

This section describes the token methods and the behaviors.

The RequestRecipientToken and RequestRecipientFaxToken methods use the format and rules, and are divided into three sections: Entity Identification, Authentication Assertions and InSessionCallBackURL.

**`C#`**

```csharp title="C#"
// Create envelope as shown in linked code
DocuSignWeb.Envelope envelope = <create envelope>;
// Need to specify captive info for these recipients
envelope.Recipients[0].CaptiveInfo = new DocuSignWeb.RecipientCaptiveInfo();
envelope.Recipients[0].CaptiveInfo.ClientUserID = "User4521";

DocuSignWeb.EnvelopeStatus status = _apiClient.SendEnvelope(envelope);

// Construct the recipient token authentication assertion
// Specify ID, start time, method and domain
DocuSignWeb.RequestRecipientTokenAuthenticationAssertion assertion = new DocuSignWeb.RequestRecipientTokenAuthenticationAssertion();
assertion.AssertionID = new Guid().ToString();
assertion.AuthenticationInstant = DateTime.Now;
assertion.AuthenticationMethod = DocuSignWeb.RequestRecipientTokenAuthenticationAssertionAuthenticationMethod.Password;
assertion.SecurityDomain = "Request Recipient Token Test";

// Construct the URLs based on username
DocuSignWeb.Recipient recipient = envelope.Recipients[0];
DocuSignWeb.RequestRecipientTokenClientURLs urls = new DocuSignWeb.RequestRecipientTokenClientURLs();
String urlBase = baseURL;
urls.OnSigningComplete = urlBase + "?event=SignComplete&uname=" + recipient.UserName;
urls.OnViewingComplete = urlBase + "?event=ViewComplete&uname=" + recipient.UserName;
urls.OnCancel = urlBase + "?event=Cancel&uname=" + recipient.UserName;
urls.OnDecline = urlBase + "?event=Decline&uname=" + recipient.UserName;
urls.OnSessionTimeout = urlBase + "?event=Timeout&uname=" + recipient.UserName;
urls.OnTTLExpired = urlBase + "?event=TTLExpired&uname=" + recipient.UserName;
urls.OnIdCheckFailed = urlBase + "?event=IDCheck&uname=" + recipient.UserName;
urls.OnAccessCodeFailed = urlBase + "?event=AccessCode&uname=" + recipient.UserName;
urls.OnException = urlBase + "?event=Exception&uname=" + recipient.UserName;

// Request the token for a specific recipient
String token = _apiClient.RequestRecipientToken(status.EnvelopeID,
recipient.CaptiveInfo.ClientUserID, recipient.UserName,
recipient.Email, assertion, urls);

// Display token
Console.WriteLine("Recipient token is {0}", token);
```

**`PHP`**

```php title="PHP"
// Create an envelope as shown in linked code
$env = <create envelope>;

// Specify captive info for recipients
$captiveInfo = new RecipientCaptiveInfo();
$captiveInfo->ClientUserId = "User4521";
$env->Recipients[0]->CaptiveInfo = $captiveInfo;

// Now send the envelope
$sendEnvelopeparams = new SendEnvelope();
$sendEnvelopeparams->Envelope = $env;
$createResult = $api->SendEnvelope($sendEnvelopeparams)->SendEnvelopeResult;

// Construct the recipient token authentication assertion and specify
// ID, start time, method, and domain
$assertion = new RequestRecipientTokenAuthenticationAssertion();
$assertion->AssertionID = guid();
$assertion->AuthenticationInstant = nowXsdDate();
$assertion->AuthenticationMethod = RequestRecipientTokenAuthenticationAssertionAuthenticationMethod::Password;
$assertion->SecurityDomain = "Request Recipient Token Test";

// Construct the URLs based on UserName
$recip = $env->Recipients[0];
$urls = new RequestRecipientTokenClientURLs();
$urlbase = "https://127.0.0.1/";
$urls->OnSigningComplete = $urlbase . "?event=SignComplete&uname=" . $recip->UserName;
$urls->OnViewingComplete = $urlbase . "?event=ViewComplete&uname=" . $recip->UserName;
$urls->OnCancel = $urlbase . "?event=Cancel&uname=" . $recip->UserName;
$urls->OnDecline = $urlbase . "?event=Decline&uname=" . $recip->UserName;
$urls->OnSessionTimeout = $urlbase . "?event=Timeout&uname=" . $recip->UserName;
$urls->OnTTLExpired = $urlbase . "?event=TTLExpired&uname=" . $recip->UserName;
$urls->OnIdCheckFailed = $urlbase . "?event=IDCheck&uname=" . $recip->UserName;
$urls->OnAccessCodeFailed = $urlbase . "?event=AccesssCode&uname=" . $recip->UserName;
$urls->OnException = $urlbase . "?event=Exception&uname=" . $recip->UserName;

// Send
$requestRecipientTokenparams = new RequestRecipientToken();
$requestRecipientTokenparams->EnvelopeID = $createResult->EnvelopeID;
$requestRecipientTokenparams->ClientUserID = $recip->CaptiveInfo->ClientUserID;
$requestRecipientTokenparams->Username = $recip->UserName;
$requestRecipientTokenparams->Email = $recip->Email;
$requestRecipientTokenparams->AuthenticationAssertion = $assertion;
$requestRecipientTokenparams->ClientURLs = $urls;
$response = $api->RequestRecipientToken($requestRecipientTokenparams);
```

![Embedded](file:docs/assets/soap/RequestRecipientToken\(Embedded\).png)

## Entity identification

The following parameters identify the Envelope and Captive Recipient for which the Recipient Token is requested:

> **Note:** When requesting a Recipient Token, the ID in ClientUserID must use upper-case letters. If lower-case letters are used (ClientUserId) an error will occur.

* **EnvelopeID** – The Docusign-generated value contained in the EnvelopeStatus object returned from the CreateAndSendEnvelope method. This parameter identifies the Envelope.
* **ClientUserID** – The value that specifies if the recipient is Remote or Embedded
* **UserName** – Specifies the username of the recipient
* **Email** - Specifies the Email of the recipient.

The Username and Email identifies a unique recipient and ClientUserID specifies if the recipient is Embedded or Remote. All the three parameter together identifies a Captive Recipient. All values must exist and correlate to a valid Envelope/Embedded Recipient entity relationship in order for the RequestRecipientToken request to succeed.

## Authentication Assertions

Docusign acts as a Single Sign-On consumer to the API client application in the Embedded Signing model. That is, Docusign trusts that the client application authenticated the end-user sufficiently to establish their identity and offer documents to sign or view. This is critical to the seamless integration between the two applications, and it is necessary since Docusign has no interaction with the end-user prior to displaying the documents. However, even though the trust relationship does not include a Docusign-verification of the user identity, Docusign requires the client application to assert that it has authenticated the end-user through some means. This assertion is communicated through the following parameters:

* **AssertionID** – A unique identifier of the authentication event executed by the client application.
* **AuthenticationInstant** – The date/time that the end-user was authenticated.
* **AuthenticationMethod** – The convention used to authenticate the end-user.
* **SecurityDomain** – The domain to which the user authenticated.

An entry is added into the Security Level section of the Docusign Signing Certificate that reflects the “SecurityDomain – AuthenticationMethod” used to verify the user identity. Additional identity verification within Docusign is optionally available through the ID Check and Access Code features.

## ClientURLs

Client application will have the option of setting Client URLs to be called on specific Docusign events. Docusign redirects the Recipient to the URL.

If you want an “event” parameter or any other parameters, you MUST provide them in the callback URL. The valid values are listed in [Embedded Callback Event Codes](/docs/esign-soap-api/reference/administrative-group/embedded-callback-event-codes).

## XML Signing

It is recommended that embedded clients sign the body of the RequestRecipientToken message with a valid X.509 certificate. This process supports the Single Sign-On trust relationship between Docusign and the client application. Client organizations must provide Docusign with the certificate’s Common Name (CN) during the implementation phase so that Docusign can validate the XML signature. Supported certificate authorities are VeriSign and Thawte.

## Expiration

* Recipient Tokens expire five minutes after they are issued by Docusign. If a Recipient Token URL is invoked after it is expired, the user is re-directed to the Callback URL specified in the RequestRecipientToken request with event code TTLExpired.
* Recipient Tokens expire upon being successfully invoked.
* Active Recipient Tokens expire if the envelope is voided.
* Five minutes is the default "Time to Live" for Recipient tokens. This is a configurable setting.

## Signing vs. Viewing Documents

Recipient Tokens must be requested (and returned) in order to sign or to view envelope documents. The Docusign web application renders the view that is appropriate to the state of the envelope for the Recipient. The logic is as follows:

* If Recipient has uncompleted signing actions, Docusign will present documents in Sign mode.
* If Recipient has completed all signing actions, Docusign will present documents in View mode.
* If Recipient has uncompleted signing actions and the envelope has been declined by another Recipient, then the remaining recipients will not be able to view the envelope.
* If the sender has voided the envelope no recipient will be able to view or sign document.