Trying to understand DocuSign API documentation but I'm getting confused - obviously I would like to have a custom built application that allows employees to digitally sign terms and conditions.
Looking at previous questions it looks like I'll need one account to represent the sender (aka "application"). I'm looking to authenticate my application with DocuSign using client credentials and secret but also to include an authorization code to get a user scoped token back from DocuSign.
Looking at the documentation the auth development endpoint is https://account-d.docusign.com/oauth/token
Calling the endpoint and getting a user scoped token back
// Header
Authorization Basic <integration_key_and_the_secret>
// Body
grant_type=authorization_code&code=<authorization_code>
If I've understood this correctly it means I need to create users beforehand within DocuSign for the process to work, i.e. so when the endpoint above is called with the user email included within the authorization_code value it matches with a user account within DocuSign.
If my understanding is correct then the "Users" endpoint makes sense, i.e. I would need to call the following POST endpoint to create each user that will use my application to sign their terms and conditions.
Create users endpoint within DocuSign
POST /restapi/v2.1/accounts/{accountId}/users
The documentation states I can create multiple users at once although there's a limit for any single request to be no more than 500 users which is ok as my application can be designed to batch users with a number limit included.
Looking for confirmation on whether I've understood the process?
Many thanks
If you want to build an app to enable "employees to digitally sign terms and conditions." then the employees will not be DocuSign "users." Rather, they will be "Signers."
The OAuth Authorization Code flow you reference in your question enables a DocuSign "user" (also known as a DocuSign "account member") to obtain an access token that can be used with the DocuSign APIs.
In your use case, it sounds like the new employee accesses a web portal (your app) and at some point presses a "Sign the Terms and Conditions" button.
In this flow, the new employee is not (yet) a DocuSign user. So they can't login to DocuSign, they can't use the OAuth Authorization Code flow, etc.
Instead, your application needs to authenticate with DocuSign by itself and then create (via the API) the Signing Ceremony for the new employee.
The answer for DocuSign eSignature API is that your application will impersonate a DocuSign user via the OAuth JWT grant flow. Most developers create a "system user" such as "HR Department" with email "[email protected]".
The DocuSign administrator adds the new "system user" to their DocuSign account and your app can then impersonate the user. Remember that the "user" needs to grant consent to your app for impersonation.
Notes
If you really do want to create new users in DocuSign, you can do that via the Admin API. But the rest of your question sounds more like you want the new employees to be DocuSign Signers not Users
DocuSign offers many features for authenticating a signer. Which authentication methods you choose often depend on the threat model for your agreements, legal requirements, past experiences (in the past, how often were signatures forged or repudiated), value of the agreement (if something goes wrong, did your company lose $10 or $10,000,000) etc.
Some of the authentication options available from DocuSign:
Yes, a user ID would be a shared secret that DocuSign could check for:
What to watch out for: how easy is it for someone to guess the new employee's user ID. Remember the problem would happen when a rogue employee violates their agreement with the company and repudiates their signature, saying they never signed it.
If your employee user ids are known within the company or easy to guess then it may not be beyond a reasonable doubt that the rogue employee actually did not sign their agreement (even though they did).
In this case the employee would be claiming that their signature was forged, where the reality is that they repudiated their real signature.
This type of example is why signer authentication is so important.
If you, the application developer, build an application that authenticates its users then you may or may not need additional authentication by DocuSign.
Example:
The admin api is used to for many actions including creating new users within a DocuSign account. Only users can send envelopes. If an employee will need to send envelopes then a new user account can be created for the new employee either manually or programmatically via the Admin API.