I am using the DocuSign API to authenticate, create, and send envelopes from within my application. This applications needs to allow multiple users to use their own DocuSign sign account with the application. For each DocuSign User that will use with this application, do I need to have a separate integrator key and private key? Or is there a better way? Requiring each user to setup an API key doesn't scale very well as a business workflow. I'm hoping there is a better way, so that I can setup an integrator key and private key once.
No you do not need to create a separate integrator key for each user! You only need one integrator key (also called clientId) per DocuSign integration. The key helps identify which integration the requests are coming from, though these requests can indeed be coming from different accounts.
Your integration simply needs to initiate the OAuth handshake based on which method you are using (Auth Code Grant, Implicit Grant, JWT Token) and while "under the hood" the request will contain your integrator key the end-user does not see that (or even know about it).
See the Authentication Overview for more info.
Once you make the initial auth request the user will be redirected to a browser where they will login through the standard DocuSign login page using their username and pwd. Upon successful login they will be redirected to the redirectUri that was supplied in the API request and the resulting URL will have a query parameter attached to it which has their auth code.
Again, read the overview above based on which method you are using, but as stated you only need ONE integrator key per integration which is a private ID that you should never share with the end-user.
Related
I have a vuejs SPA. Users have their own accounts with a dashboard. On the dashboard, is a section for PDF signing. All users should have the same PDF displayed, but with their name pre-filled on the PDF, and then 4 spots to sign.
Right now I am stuck on the first part for using the API....which is the auth code.
Why does it seem that the tutorial I followed, requires the owner of the DocuSign account to login and grant rights? I had to do something similar to https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature&client_id=5665656-3506-46fa-b46d-f6acf3b59268&redirect_uri=https://www.google.com and I got a code in return....but how am I even suppose to implement this for my web app?
How do I get the auth code in the background....meaning...I cant have all users go to this URL...am I supposed to do it via ajax GET? I was able to use a correctly formatted URL, but I got the response by visiting the URL in my browser...how can I do this programmatically?
I dont get the granting rights part....because there is no way this would be practical where all the users would have to know my private DocuSign account info?
Of the (3) oauth methods, which is best for my scenario? Authorization Code Grant, Implicit Grant, or JWT Grant
Auth Code Grant was meant for interactive scenarios. It requires UI and a web interface. It cannot be used without UI. Once you have the initial access token, there's a refresh token to be able to obtain a new one without UI, but the initial call requires UI.
The users don't have to know your account info, your account info may not be relevant. The user grant a right to your app/integration to make API calls. That is not your account, it is different. It's a clientId/integration key that you use your account to create, but it can be used with any DocuSign user/account.
JWT would allow for what you asked in #1 but only after a one-time consent was provided (What you asked in #2) by the end-user. You have to do that for users to enable DocuSign to make API calls on their behalf.
Final word, signers do not need an account in DocuSign. I don't know what you're building, but if your end-user just signs - they don't need an account and a lot of 1-3 is moot.
I'm using a legacy service integration with DocuSign (through custom X-DocuSign-Authentication header attribute) and I'm a bit confused with the relationship between username and Integrator-Key.
For example, for test purposes I've used the following scenario:
I've send a request to sign a document and obtained the envelopeId using Integrator-Key-1
After I'm sending a request to get the recipient view url (for embedded signing) using the same credentials and provided envelopeId, but another Integrator-Key-2
I was expecting that the request should fail, but it works fine and the document is displayed for signature.
I'm getting the same result even in case the provided integrator key belongs to different user.
So, I'm really confused what the integrator-key is used for.
Thank you.
The integrator key identifies the integration. Once approved for use within a specific DocuSign environment (e.g., demo, prod), an integrator key can be used to issue API requests for data affiliated with any Account and/or User within that environment (provided, of course, that each API request includes proper info to authenticate the User who's making the API request).
So, for example, if you're an ISV who's building an integration that will be used by multiple customers across multiple DocuSign Accounts, you can use the same integrator key for all API calls that your integration issues, regardless of the Account and/or User affiliated with any particular request.
Integrator key (also known as a client id) is a unique identifier that authenticates your account with the DocuSign API. If you have two Integrator Keys for the same environment then you will be able to call DS APIs with any Integrator Key. But Integrator Key has more value for DocuSign, for instance if you have created an application with DS APIs with IK 1 and you reviewed this IK to be used in the PROD environment. After you have passed the review process, IK will be promoted to PROD environment enabling you to call DS APIs in Live/Prod environment within API rules and limits. Now in future you did any code changes on your end and your newly deployed code was not developed as per DS API Rules and Limits then DS can blacklist your IK to not to be used in PROD, which will impact your application to be stopped in the PROD directly.
I have set up Sandbox account and successfully created integrator keys for my apps REST API calls. I have docusign header (X-DocuSign-Authentication) on my code that requires username/password/integrator key for api connections. I used DocuSign ApiClient & AuthenticationApi to set it up in code. Looks good on sandbox. My question is when we go live, on production, the admin account is an individual user credential (not a generic admin account). So how can we have that set -up in every application for the REST api connections header?
For "User Applications" -- where an individual logs in and later sends envelopes -- it is vastly preferred that you use OAuth to authenticate the users. See the docs. See a recipe example of using OAuth.
If you want to use Legacy Authentication (the X-DocuSign header) for a user application, then your app needs to request (and securely store) the user's DocuSign email and password. These days, this is a not a good plan.
As you know, you must include the username and pw in each call to DocuSign if you use the Legacy Authentication scheme. The data is secure since it is within an https conversation. But requesting and storing the pw from your users is problematic.
These days, Legacy Auth should only be used for "Service Integrations" -- DocuSign integrations where there is no human involved, just an autonomous / batch process that sends out the signing requests.
We are implementing embedded document creation for our SaaS product. Some of our clients will be using their own accounts and credentials. Others may not have a DocuSign account and so will be able to set one up through us. How does a client authorize us to use their account credentials?
For example, say we want to create an authorization token to store on behalf of one our clients (i.e. post to ~/v2/oauth2/token). Would we pass our account's integrator key, with the client's username and password in the headers?
You should think of the Integrator Key as an application specific key - it helps identify your integration so DocuSign knows which integration is creating which envelopes as well as how many envelopes (especially since there are per account per hour API call limits in place).
You only need one Integrator Key for any and all users using your integration, and yes you would authenticate your API calls by placing the IK along with a given user's username and password in the authorization header. As long as that user is passing valid credentials (ie valid username + pwd combo) then they can make the request under any Integrator Key).
I figured this has been answered before, but a quick SO search didn't yield anything.
I have a private API that is locked down by an APIKey. This key needs to be passed for each request. With this key you can access any part of the API. Obviously that's pretty open. For the most part this is acceptable. However, there are cases where I want to ensure that the request is sent by the owner of the data.
For example, consider an update or delete request. You shouldn't be able to make this request for someone else's data. So in addition to the APIKey, I'd like to have something else to ensure that this user making the request is authorized to perform that action.
I could require that an ownerID be passed with such request. But that's quickly forged. So what have I gained.
I am interested to hear what other members of SO have implemented in these situations. Individual APIKeys? Dual-authorization?
If it matters, my API follows the REST architecture and is developed with PHP/Apache.
API keys should be unique per user. This will verify the user and that they should have access to the data.
If you want to be even more secure you can have that api secret be used as a refresh token that can be used to retrieve an access token with an automated expiration.
SSL for all requests is also suggested.
Each API user has a unique API key. This key identifies them as a single user of the system. When dealing with more sensitive data, I've used client side certificates for auth, however Basic Auth + requiring SSL is usually sufficient.
When the request comes in, map the API key to the user and then determine if that user "owns" the resource they are trying to interact with.
The whole "determine the owner" part is a separate issue that can be tricky to do nicely in an API depending on how well the system was built. I can share how we've done that in the past as well, but figured that's a bit off topic.
Suggest you should consider using Oauth. In summary this is how it should work.
Each application making the API calls will need the respective application level APIkey for authorization through the Oauth process. Apikey here would just represent the application (client) identity.
Each end-user associated with the usage must authenticate themselves separately (independent of the apikey) during the Oauth authorization process. The users identity, associated context such as scope of authorization is then encoded into a token called access token.
Once the application obtains this access token, all subsequent API calls to access resources should use the access token, until expiry.
On the API implementation side, the access token validation should reveal the end-user context (including the scope of access that is granted during the Oauth process) and hence the access/authorization to use a specific resource can be managed by the resource server.