Docusign API Auth - which to use

Question

Just getting started implementing Docusign on my website. (.NET VB.NET)

Need to make sure I am choosing the right type of authorization to access the API.

Users will log in to the website and select documents to send to specified recipients.

The company will have one overall DocuSign account used for all document signings. Users will not have individual DocuSign accounts but they will have individual log in credentials to the website.

I think this is a JWT situation but not sure. Is there a simpler way to authorize each signing?

Thanks for any ideas.

Answer 1

I finally got it working with vb.net. There is apparently no documentation for us vb developers so in case it might help someone else, I post my code here. process starts with the procedure "Button1_Click".... It sends the documents to the recipients for signature and returns the Docusign result response to a textbox "txtResult". This is based on the demo processes in the C# Documentation as converted to vb.net. The private key is read from a local .txt file which contains the key including the -----BEGIN PRIVATE KEY---- and ----END PRIVATE KEY---- flags.

Imports System.IO
Imports System.Net
Imports System.Text
Imports DocuSign.eSign.Api
Imports DocuSign.eSign.Client
Imports DocuSign.eSign.Client.Auth
Imports DocuSign.eSign.Model


Partial Class DocusignTest
    Inherits System.Web.UI.Page
'---------------------------------------
    'Process Begins With This Button Click....
    Protected Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
        txtResult.Text = SendEnvelopeViaEmail("recip1@wherever.com",
                                              "Recip1 Name",
                                              "recip2@anotherplace.com",
                                              "Recip2 Name",
                                              GetaccessToken(),
                                              "https://demo.docusign.net/restapi",
                                              "Your Account ID",
                                              "C:\Users\Dotne\Downloads\World_Wide_Corp_Battle_Plan_Trafalgar.docx",
                                              "C:\Users\Dotne\Downloads\World_Wide_Corp_lorem.pdf",
                                              "sent")
    End Sub

'---------------------------------------
    Public Shared Function SendEnvelopeViaEmail(ByVal signerEmail As String,
                                                ByVal signerName As String,
                                                ByVal ccEmail As String,
                                                ByVal ccName As String,
                                                ByVal accessToken As String,
                                                ByVal basePath As String,
                                                ByVal accountId As String,
                                                ByVal docDocx As String,
                                                ByVal docPdf As String,
                                                ByVal envStatus As String) As String
        '/ <summary>
        '/ Creates an envelope that would include two documents and add a signer and cc recipients to be notified via email
        '/ </summary>
        '/ <param name="signerEmail">Email address for the signer</param>
        '/ <param name="signerName">Full name of the signer</param>
        '/ <param name="ccEmail">Email address for the cc recipient</param>
        '/ <param name="ccName">Name of the cc recipient</param>
        '/ <param name="accessToken">Access Token for API call (OAuth)</param>
        '/ <param name="basePath">BasePath for API calls (URI)</param>
        '/ <param name="accountId">The DocuSign Account ID (GUID or short version) for which the APIs call would be made</param>
        '/ <param name="docPdf">String of bytes representing the document (pdf)</param>
        '/ <param name="docDocx">String of bytes representing the Word document (docx)</param>
        '/ <param name="envStatus">Status to set the envelope to</param>
        '/ <returns>EnvelopeId for the new envelope</returns>
        Dim env As EnvelopeDefinition = MakeEnvelope(signerEmail, signerName, ccEmail, ccName, docDocx, docPdf, envStatus)
        Dim apiClient As ApiClient = New ApiClient(basePath)
        apiClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " & accessToken)
        Dim envelopesApi As EnvelopesApi = New EnvelopesApi(apiClient)
        Dim results As EnvelopeSummary = envelopesApi.CreateEnvelope(accountId, env)
        Return results.EnvelopeId
    End Function
'---------------------------------------
    Private Shared Function MakeEnvelope(ByVal signerEmail As String, ByVal signerName As String, ByVal ccEmail As String, ByVal ccName As String, ByVal docDocx As String, ByVal docPdf As String, ByVal envStatus As String) As EnvelopeDefinition
        ' Data for this method
        ' Config.docDocx
        ' Config.docPdf
        ' RequestItemsService.Status -- the envelope status ('created' or 'sent')
        ' document 1 (html) has tag **signature_1**
        ' document 2 (docx) has tag /sn1/
        ' document 3 (pdf) has tag /sn1/
        '
        ' The envelope has two recipients.
        ' recipient 1 - signer
        ' recipient 2 - cc
        ' The envelope will be sent first to the signer.
        ' After it is signed, a copy is sent to the cc person.
        ' read files from a local directory
        ' The reads could raise an exception if the file is not available!

        Dim document1 = Encoding.UTF8.GetBytes(" <!DOCTYPE html>\n" &
                    "    <html>" &
                    "        <head>" &
                    "          <meta charset='UTF-8'>" &
                    "        </head>" &
                    "        <body style=""font-family:sans-serif;margin-left:2em;"">" &
                    "        <h1 style=""font-family: 'Trebuchet MS', Helvetica, sans-serif;" &
                    "            color: darkblue;margin-bottom: 0;"">World Wide Corp</h1>" &
                    "        <h2 style=""font-family: 'Trebuchet MS', Helvetica, sans-serif;" &
                    "          margin-top: 0px;margin-bottom: 3.5em;font-size: 1em;" &
                    "          color: darkblue;"">Order Processing Division</h2>" &
                    "        <h4>Ordered by " & signerName & "</h4>" &
                    "        <p style=""margin-top: 0em; margin-bottom:0em;"">Email: " & signerEmail & "</p>" &
                    "        <p style=""margin-top:0em; margin-bottom:0em;"">Copy to: " & ccName & ", " & ccEmail & "</p>" &
                    "        <p style=""margin-top:3em;"">" &
                    "  Candy bonbon pastry jujubes lollipop wafer biscuit biscuit. Topping brownie sesame snaps sweet roll pie. Croissant danish biscuit soufflé caramels jujubes jelly. Dragée danish caramels lemon drops dragée. Gummi bears cupcake biscuit tiramisu sugar plum pastry. Dragée gummies applicake pudding liquorice. Donut jujubes oat cake jelly-o. Dessert bear claw chocolate cake gummies lollipop sugar plum ice cream gummies cheesecake." &
                    "        </p>" &
                    "        <!-- Note the anchor tag for the signature field Is in white. -->" &
                    "        <h3 style=""margin-top:3em;"">Agreed: <span style=""color:white;"">**signature_1**/</span></h3>" &
                    "        </body>" &
                    "    </html>")

        Dim doc2DocxBytes As String = Convert.ToBase64String(System.IO.File.ReadAllBytes(docDocx))
        Dim doc3PdfBytes As String = Convert.ToBase64String(System.IO.File.ReadAllBytes(docPdf))
        ' create the envelope definition
        Dim env As EnvelopeDefinition = New EnvelopeDefinition()
        env.EmailSubject = "Please sign this document set"

        ' Create document objects, one per document
        Dim doc1 As Document = New Document()
        Dim b64 As String = Convert.ToBase64String(document1) '(signerEmail, signerName, ccEmail, ccName)
        With doc1
            .DocumentBase64 = b64
            .Name = "Order acknowledgement" ' can be different from actual file name
            .FileExtension = "html" ' Source data format. Signed docs are always pdf.
            .DocumentId = "1" ' a label used to reference the doc
        End With
        Dim doc2 As Document = New Document
        With doc2
            .DocumentBase64 = doc2DocxBytes
            .Name = "Battle Plan"
            .FileExtension = "docx"
            .DocumentId = "2"
        End With
        Dim doc3 As Document = New Document
        With doc3
            .DocumentBase64 = doc3PdfBytes
            .Name = "Lorem Ipsum"
            .FileExtension = "pdf"
            .DocumentId = "3"
        End With


        ' The order in the docs array determines the order in the envelope
        Dim DocList As New List(Of Document)
        DocList.Add(doc1)
        DocList.Add(doc2)
        DocList.Add(doc3)
        env.Documents = DocList

        ' create a signer recipient to sign the document, identified by name and email
        Dim signer1 As Signer = New Signer
        With signer1
            .Email = signerEmail
            .Name = signerName
            .RecipientId = "1"
            .RoutingOrder = "1"
        End With
        ' routingOrder (lower means earlier) determines the order of deliveries
        ' to the recipients. Parallel routing order is supported by using the
        ' same integer as the order for two or more recipients.

        ' create a cc recipient to receive a copy of the documents, identified by name and email
        Dim CC1 As CarbonCopy = New CarbonCopy
        With CC1
            .Email = ccEmail
            .Name = ccName
            .RecipientId = "2"
            .RoutingOrder = "2"
        End With

        ' Create signHere fields (also known as tabs) on the documents,
        ' We're using anchor (autoPlace) positioning
        '
        ' The DocuSign platform searches throughout your envelope's
        ' documents for matching anchor strings. So the
        ' signHere2 tab will be used in both document 2 and 3 since they
        ' use the same anchor string for their "signer 1" tabs.
        Dim signHere1 As SignHere = New SignHere
        With signHere1
            .AnchorString = "**signature_1**"
            .AnchorUnits = "pixels"
            .AnchorYOffset = "10"
            .AnchorXOffset = "20"
        End With
        Dim signHere2 As SignHere = New SignHere
        With signHere2
            .AnchorString = "/sn1/"
            .AnchorUnits = "pixels"
            .AnchorYOffset = "10"
            .AnchorXOffset = "20"
        End With

        ' Tabs are set per recipient / signer
        Dim signer1Tabs As Tabs = New Tabs
        Dim SignHereList As New List(Of SignHere)
        SignHereList.Add(signHere1)
        SignHereList.Add(signHere2)
        signer1Tabs.SignHereTabs = SignHereList
        signer1.Tabs = signer1Tabs

        ' Add the recipients to the envelope object
        Dim Recipients As Recipients = New Recipients
        Dim Signers As New List(Of Signer)
        Signers.Add(signer1)
        Dim CarbonCopies As New List(Of CarbonCopy)
        CarbonCopies.Add(CC1)
        Recipients.CarbonCopies = CarbonCopies
        Recipients.Signers = Signers
        env.Recipients = Recipients

        ' Request that the envelope be sent by setting |status| to "sent".
        ' To request that the envelope be created as a draft, set to "created"
        env.Status = envStatus
        Return env
    End Function

'---------------------------------------
    Private Function GetaccessToken() As String
        Dim ac As ApiClient = New ApiClient()
        Dim privateKeyStream() As Byte = System.IO.File.ReadAllBytes("c:\scratch\privatekey.txt") 'Location of file with Private Key.
        Dim tokenInfo As OAuth.OAuthToken = ac.RequestJWTUserToken("Your Client ID",
                                                                   "Your User ID",
                                                                   "account-d.docusign.com",
                                                                   privateKeyStream,
                                                                   1)


        Return tokenInfo.access_token

    End Function
'---------------------------------------
End Class

Answer 2

Sounds like JWT to me. Also note the following:

JSON Web Token (JWT) authentication enables developers to request a token on behalf of some user without that user having to log in. That means that except for the first time, when the user has to consent, there's no web UI required to obtain a token. JWT tokens are for a specific user in a specific account, and it's the GUID of that user ID that is used to uniquely identify a user. If you have multiple accounts, you will have to ensure you use the right user ID for the right user for the right account. Note also that users in DocuSign have different permission profiles and may or may not have the access required to do what the API is trying to do. JWT may not be the best option for web applications enabling many different users to send envelopes using their own DocuSign login. For these scenarios, Authorization Code Grant is a more suitable model, as it requires the end user to log in to DocuSign with their credentials before a token for accessing the API is generated.