Skip to navigation
Plan a Web Forms API integration

Authentication

View as Markdown

The Web Forms API is available in all developer accounts, but only in certain production account plans. Contact Docusign Support or your account manager to find out whether the Web Forms API is available for your production account plan.

Before your application can make calls to the Web Forms API, it must authenticate and obtain an access token. You must submit this access token, which proves your application’s identity and authorization, with each request.

You can use these supported OAuth2 authentication workflows to obtain an access token and make calls to the Web Forms API:

  • Authorization Code Grant: For the highest level of security, Docusign recommends using this authentication method when possible.
  • Implicit Grant: This authentication method can be used with public clients, as defined in RFC 6749 section 2.1. Implicit Grant must be used for applications that are not able to store sensitive data on a secure server.
  • JSON Web Token (JWT) Grant: With this authentication method, the access token impersonates a user, also known as an account member. Use JWT Grant for heavily automated applications that call the Docusign platform without direct user interaction.

See the platform authentication overview for a description of these grants and how to choose between them.

Required scopes

When you request an access token for your OAuth2 scenario, you must request Web Forms API scopes during the authentication process.

The eSignature REST API signature scope is required for Web Forms API requests, in addition to Web Forms API scopes. For JWT Grant, the impersonation scope is also required.

The Web Forms API supports these scopes:

ScopeDescriptionRequired for these requests
webforms_readAllows an application to retrieve information about web form configurations defined in an account.Configurations:getForm

Configurations:listForms
webforms_instance_readAllows an application to retrieve information about web form instances.Instances:getInstance

Instances:listInstances
webforms_instance_writeAllows an application to create web form instances and refresh instance tokens.Instances:createInstance

Instances:refreshToken
signatureUsed for operations on the Docusign eSignature API.Required for requests to all Web Forms API endpoints.

The scopes request is included in these authentication flow components:

  • Authorization Code Grant: The authorization code request
  • Implicit Grant: The access token request
  • JWT Grant: The body of the JWT token

See Authentication examples for details.

Authentication examples

Authorization Code Grant

Request URL

https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20webforms_read%20webforms_instance_read%20webforms_instance_write&client_id=7c2b8d7e-xxxx-xxxx-xxxx-cda8a50dd73f&redirect_uri=http://example.com/callback/

Implicit Grant

Request URL

https://account-d.docusign.com/oauth/auth?response_type=token&scope=signature%20webforms_read%20webforms_instance_read%20webforms_instance_write&client_id=7c2b8d7e-xxxx-xxxx-xxxx-cda8a50dd73f&redirect_uri=http://example.com/callback/

JSON Web Token (JWT) Grant

Request URL

https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation%20webforms_read%20webforms_instance_read%20webforms_instance_write&client_id=7c2b8d7e-xxxx-xxxx-xxxx-cda8a50dd73f&redirect_uri=http://example.com/callback/

JSON request body

{
  "iss": "5c2b8d7e-xxxx-xxxx-xxxx-cda8a50dd73f",
  "sub": "464f7988-xxxx-xxxx-xxxx-781ee556ab7a",
  "iat": 1705602811,
  "exp": 1705606811,
  "aud": "account-d.docusign.com",
  "scope": "signature impersonation webforms_read webforms_instance_read webforms_instance_write"
}

Next steps