Single Sign On using the EchoSign Document API
Basic Overview
The EchoSign Document API is designed to seamlessly integrate into your existing application without requiring the user to go through a separate EchoSign-managed registration process. This means that the enclosing application is responsible for ensuring that the sender is a registered EchoSign user, and registering them programatically through the API if they are not. Note that the recipients are never required to register, and EchoSign will always manage whatever interactions are necessary on the recipient side.
Specifying a Document Sender
There are several ways to specify a sender when starting a new transaction with the sendDocument method. The behavior depends on what values are passed in through the optional SenderInfo parameter.
- Null SenderInfo - In this case, the sender of the document is the specific unique user associated with the API Key being used. This is appropriate in testing and certain limited-scope implementations, but is not typically useful for large scale integrations with existing user sets.
- SenderInfo with email and password - In this case, the sender of the document will be the user specified by the email parameter. The password provided must match the user's EchoSign password. For purposes of integration, the email and password can be solicited from the user within the context of the enclosing application when the document is about to be sent. Alternatively, the email and password can be remembered by the enclosing application, either because the enclosing application created the user or because the user previously provided this information and it has been cached.
- SenderInfo with email and no password - In this case, the sender of the document will be the user specified by the email parameter. The password value must be null. EchoSign will verify that the API caller and the intended sender belong to the same account, but will not require or check the password. This method is sometimes appropriate for API integrations within a specific organization, but it should be noted that this offers reduced individual security. This authentication model must be explicitly requested by the master account holder in order to be available for use through the EchoSign API.
EchoSign Account Management
As outlined above, in most cases you will want to provide the email and password of the user on whose behalf you're sending the document. The following section outlines the different ways that information can be obtained.
Prompt the User
Prompt the user for their EchoSign email and password as part of the sending process. You can use the verifyUser method to check that the user is registered with EchoSign and the password is valid. If the user is unregistered you can either ask them to create their own EchoSign account or create one for them (see below).
Create the Account
If a call to verifyUser shows that no user exists with that email address, you can programmatically create a new EchoSign user by calling createUser. Assuming the user creation was successful, the email and password that you provided can now be used as the SenderInfo for your document.
Remember the Account
Subsequent to either of the scenarios above, you can then remember the user's email and password and use them as the SenderInfo for sending subsequent documents on behalf of that user. Note that it's possible that the user will actually log into their EchoSign account and change their password at any time, so your application must be able to handle the case of a previously saved password being invalid.
Conclusion
There are a number of different ways to determine sender identity when using the EchoSign Document API. Please read the above information carefully to decide which method is appropriate for your application. If you have any questions, please don't hesitate to contact us.