Single-page applications and CORS

eSignature REST API 2.1 only

Developers can build Docusign integrations as single-page applications (SPAs) that run in a web browser. Because SPA integrations launch API requests from scripts that run on a web page, the requests are subject to browser security restrictions. To address this, Docusign supports Cross-Origin Resource Sharing (CORS), which enables SPAs to meet browser security requirements and send requests directly to Docusign.

By enabling SPAs to communicate directly with Docusign, CORS support makes SPAs easier and less costly to build, as no web server or proxy server is needed for routing API calls. Eliminating these components also improves SPA performance. CORS can be used with SPAs running scripts written in JavaScript and in any framework, including React, Vue.js, Angular, and jQuery.

Supported API, version, and endpoints

The eSignature REST API v2.1 supports CORS. You can use CORS with all eSignature endpoints that have an account ID in the path. The following eSignature categories, resources, and endpoints do not include the account ID, and as a result, do not support CORS:

• Accounts:getProvisioning
• BillingPlans Resource
• Diagnostics Category
• Notary Category

Requirements for an app to use CORS

To use CORS, an app must meet the following requirements:

• It has been configured for CORS in the eSignature web app.
• It uses a supported authentication method and requests the cors scope.

Configure apps for CORS

CORS configuration settings appear at two levels in the eSignature web app. Your role determines the settings to which you have access:

• If you are an application owner, partner, or independent software vendor (ISV), you define these CORS configuration parameters for each app:

  • Allowed HTTP methods (POST, PUT, etc.) for API requests that use CORS
  • Allowed origins for CORS requests. Each defined origin represents the domain, protocol (http or https), and optional port of a script that will launch CORS requests.
  • The authentication method. See Include required scopes during authentication for information about supported authentication methods.
  • If the app uses the Public Authorization Code Grant authentication method, the option to allow CORS for OAuth calls must be enabled.

• If you are an account administrator, you configure account-level settings that:

  • Enable or disable CORS by default for apps used with your account. By default, CORS is allowed for all applications.
  • Enable or disable CORS for specific apps used with your account.

Docusign checks the settings at both levels when determining whether to accept a CORS request.

You may have access to both the account-level settings and the app-level CORS configuration parameters. If you do not, keep the following in mind:

• Application owners, partners, and ISVs: To use your app, your users must grant consent to it, and their account administrator must enable CORS. If a user’s account administrator has not enabled CORS and your app makes CORS requests while authenticated as that user, Docusign will return an error. Your user’s account administrator can enable CORS for all apps or for just your app.
• Account administrators: If you choose not to enable CORS by default, Docusign will reject CORS requests from apps that have authenticated as a user in your account. If you want Docusign to accept CORS requests under your account from specific apps, update the account-level settings.

With CORS enabled, both CORS and non-CORS requests can be made under an app’s integration key. For example, an SPA can send CORS requests and a client-server integration can send non-CORS requests using the same integration key. If CORS requests are disabled, an app can still make non-CORS requests under that integration key.

Include required scopes during authentication

To send CORS API requests to Docusign, an app must first authenticate using one of these supported OAuth methods:

• Public Authorization Code Grant

• Implicit Grant

  Docusign recommends using Public Authorization Code Grant, without a secret, for SPAs because it provides better security. This is consistent with the OAuth v2.1 RFC. If you want to change an existing SPA’s authentication method from Implicit Grant to Public Authorization Code Grant, you must create a new integration key for the app, set the authentication method, and then modify your SPA code to implement Public Authorization Code Grant and reference the new integration key.

  The authentication process consists of:

1. Authenticating the user on whose behalf the app will make API requests. During this step, the app directs a user’s browser to an authorization URI. This URI must include one or more authentication scopes that specify permitted sets of actions. For an eSignature REST API integration that uses CORS, include the following in the scope parameter of the authorization URI:

   • signature: The basic scope for most eSignature endpoints

   • cors: The scope required to send CORS requests

     As part of the OAuth flow, Docusign will show the user a consent screen if that user has not previously granted consent for the application and its scopes.

     Note: This step does not use CORS for Implicit Grant authentication. It does use CORS for authentication via Public Authorization Code Grant.

2. Calling the UserInfo endpoint to obtain account information. This endpoint supports CORS.

The result of the authentication process is an access token that the SPA will use to make eSignature API calls. For details about this process, see How to get an access token using Public Authorization Code Grant or How to get an access token with Implicit Grant.

Error responses

Docusign returns a 403 Forbidden error or a 400 Bad Request error in response to CORS requests that cannot be completed. See CORS error responses for more information.

Next steps

For more information about how to implement CORS with an SPA, see:

• How to request a signature by email using CORS
• How to request a signature through your CORS-enabled browser app

For information about enabling and configuring CORS, see:

• Enable or disable CORS for apps
• The CORS configuration section of the Configure your app page

For information about authentication and consent, see:

• How to get an access token using Public Authorization Code Grant
• How to get an access token with Implicit Grant
• How to obtain individual consent

For information about CORS errors and troubleshooting, see CORS error responses.