I have a question regarding base URI with user and account objects in REST API.
To summarize:
one user can have multiple account attached,
one account is attached to one company,
without OAuth, we can get base URI by calling API /login_information,
with OAuth, we can get base URL by calling API /oauth/userinfo
Is it right ?
If yes, can we say that one base URI is attached to one account and will be the same for every user attached to this account ?
In addition, is it possible to get base URI by calling an endpoint dedicated to the account, and not the user ?
Thanks in advance for your answer.
Everything you write is correct, you understand this pretty well.
The reason you cannot use an account API endpoint to find the baseUrl is the architecture of how this works. The DocuSign code is deployed to many data-centers, but it's the same code. The same APIs run on na2, eu1, au etc. etc. So they are not aware directly that they have a different baseUri than other data centers.
The OAuth endpoints are different/separate and can get information from all data centers.
OAuth is always about a specific user, because you cannot login directly to an account, but you have your own user that you use. An account is shared, but each user has their own password.
The only way to do something remotely similar to what you're asking is if you use the DocuSign organization feature.
You can then use the DocuSign Admin API to obtain information about the organization and the accounts in it. That information includes a siteId that tells you if it's on na1, na2, eu1 etc. Using that you can construct the baseURI.
Lots of limitations to this, so not sure that would help you.
Related
My use case is thus:
I will have access to a single DocuSign account which would belong to Acme Inc. (I am currently using a sandbox account).
Acme Inc. has many branches, each with it's own employees with different documents that they must sign depending on which branch they work in.
From my internal application, the Admins of the branches will upload documents and set the emails addresses that the documents must be sent to.
The employees will complete the signing ceremony after following the link in the mail that they will receive.
MAIN ISSUE - Once the signing ceremony is complete, I require the employee to be redirected to a certain page of the internal application where they must complete some additional steps.
What I have so far:
I ran the example provided here. The issue with this is the permission request. I do not want an access prompt, rather, I want this done in the Admin Panel itself so that requests to the DocuSign API from my Server Application contain a valid token or receive a new one in case the existing one has expired. I saw from here that the JWT Grant system fit my use case, and I ran that using consent from a single user, however, I am stuck trying to figure out how to redirect the signer (employee) to the page I want with some parameters in the redirection URI. This can be as simple as the one provided (state=123) in the (eg-01) Embedded Signing example provided with the Auth Grant sample.
I apologize for not having any code snippet to show as I have not integrated anything into my internal application as of yet, I am merely running the code from the GitHub examples. Please let me know if I need to provide any additional information in order to facilitate your understanding of my requirements.
Any help provided would be much appreciated!
I think your main issue is the authentication type you are using.
You used the example showing Auth Code Grant, which does require users to log in.
You could instead use JWT (JSON Web Token) which does not require that (only once, and that can be done by you).
The code for making APIs and redirecting after signing ceremony etc. is the same. All you have to do is change the code that was used to obtain the access token (and also you need some configuration changes).
You can find nodeJS example of JWT here - https://github.com/docusign/eg-01-node-jwt
If you want to read more about JWT - https://developers.docusign.com/esign-rest-api/guides/authentication/oauth2-jsonwebtoken
I have some doubts regarding the custom connector we are trying to build for docusign : -
Regarding the license plan that need to be bought by the customers who will be granting access for our connector to collect data from their docusign organization account. I am looking at the link https://www.docusign.com/products-and-pricing. API access support is mentioned in only the advanced solution. So I was wondering whether only we need to have "Advanced solutions plan with APIs support" plan or all our customers need to API access support in order to fetch their data.
As per the documentation, to make the REST API calls we need two fields 'base_uri' and 'account_id' (https://developers.docusign.com/esign-rest-api/guides/authentication/user-info-endpoints). Now, the response of userInfo API call gives an array of accounts and its respective fields. My doubt is, if multiple authenticated users (more than one accounts) are returned in this array but all are part of same organization, will they all have different account_ids. Main concern here is, will there be several Base Paths (https://developers.docusign.com/esign-rest-api/guides/authentication/user-info-endpoints#form-your-base-path) to make API calls?
2a. Further question is, what is the significance of 'is_default' field?
Is this related to main account (if is_default is true) using which we will create our Base Path?
Since this is a tech/engineering forum I'm going to answer only question #2 as question #1 is more of a business/sales question.
The reason you may get multiple accounts is that an authenticated user in DocuSign can be a member of multiple accounts. That said, it's the same user. Meaning, say foobar#blah.com has an account 123 with company X and account 456 with his school, then it's possible that when foobar#blah.com authenticates (With the same password!) to DocuSign we have a list of accounts associated with that user. We give you all of them when you make the API call. The default one is the main one that you would see when you log into our web app. You can decide yourself as the user which one is the default. Users who log into our web-app then see an option at the top-right to change accounts.
and yes, every API call is associated with a specific account. So when you construct the urls for your API - you do need to know which account for this user you are making the API call for. Your application can decide how to handle this.
Hope this helps.
I'm making an app that authenticates a coach with KA's API, in order to present statistics and reports on the progress of each student.
How do I see "For whom am I a coach" (inverse of /api/v1/user.coaches)?
or otherwise request user and progress data for all my students?
You can request /api/v1/user/students to get a list of the currently authenticated users' students. Note that this is an undocumented endpoint, not sure if that's on purpose or not, but I suspect just an oversight because IIRC I've seen them reference it on github issues in the past.
I added that endpoint to the khan npm module in this PR: https://github.com/weo-edu/khan/pull/4
An important caveat to note is that as of this writing, you won't be able to request students on behalf of a user who has authenticated your application, only the user who created the app you're currently using.
Put another way: If I create an application called "hello" while logged in as "Jeffrey", I can get all of Jeffrey's students by authenticating with the "hello" app. However, If I log in as Lisa via the "hello" app (via oauth, e.g. passport-khan), I'll have an access token but the Khan API will refuse my request because Lisa did not create the "hello" app.
This behavior is documented (albeit a bit confusingly) in this wiki page, here's the relevant paragraph:
It is recommended that schools have one teacher/coach account that registers for an API key. This enables a situation where the logged-in user is the same as the third-party developer, who then can access their own students' data pursuant to Khan Academy's "coach" relationship. For example, suppose the principal of Riverdale High wished to export data for multiple students via the API. The principal would create a teacher/coach account, perhaps called "RiverdaleHighAPI," and register for an API key. The principal would then ask all students of Riverdale High to add "RiverdaleHighAPI" as a coach, either directly or via several class codes. When accessing the API with "RiverdaleHighAPI" as the logged in user, the principal would be able to access the data for all students that have added "RiverdaleHighAPI" as a coach. The app would not have access to any other coaches' student data, even if another coach logged in through the app. To protect student privacy, we do not allow indirect consent through the coach, and we require each student to explicitly grant permission to access their data. Please note that we are working to improve this functionality; for the time being, this "RiverdaleHighAPI" account should only be used by the school's API client, not by any actual teacher or coach.
Lastly, khan actually encourages public use of their internal API. They recommend opening up your developer console while logged in to khan and looking for the endpoints that return the data you want. (see this note on their authentication document).
This is obviously a fairly non-standard practice and I assume the endpoints would be subject to breaking changes without warning. Also you'll be flying documentation free. That said, this approach may be the most robust option for your purposes. Here's the quote from their wiki for posterity:
The API explorer documents our public API, which has URLs starting with /api/v1, but unfortunately it's not very well-maintained and lacking in a few areas.
If you're feeling adventurous, though, you're welcome to use any internal undocumented API endpoints. For example, if you load a Khan Academy video page and use your browser's developer tools to look at the ajax requests being sent, you'll see that it gets a URL like /api/internal/videos/aubZU0iWtgI/transcript, which contains a JSON response with the video subtitles. That "internal" in the name means that we don't provide documentation, and we may remove the endpoint or change the format in the future, but you're welcome to use any internal endpoints if you keep those caveats in mind.
Is the baseUrl value returned per user or can it be used by all future users of the same account? I want to cache this value and as far as I can tell this is actually an account setting even though it's only retrieved after a user specific login. Any chance two users of the same account could have a different baseUrl? Just want to know at what level i really need to cache this.
thanks,
-mike
It is Per Account
Is the baseUrl value returned per user or can it be used by all future
users of the same account?
restapi/v{#}/login_information
This call will give you back the list of accounts that the username/password has access to. Along with the list of accounts, you'll receive the baseUrl for that account.
baseUrl defines two things:
The server that the account resides on
The account number
If there is a specific account that you're going to add users to, the baseUrl will be the same for future users of that account.
If you do not have multiple accounts logging into your application.
You can cache the information from this call so you don't have it in every workflow. It is mostly used for setting up new workflows and moving between Demo and Production.
If you do have multiple accounts logging into your application.
I would advise that you call this information at the start of your workflow. It'll ensure that you're calling the correct account for that user.
One thing to keep in mind, that 1 set of username / password can have access to multiple accounts. So you may receive more than 1 array as a response, your application should handle this accordingly.
DocuSign's LoginInformation method enables the implementation to provide dynamic re-direction of the clients at a macro-level.
Currently, or in the future, DocuSign might use the feature for a number of different reasons that I can imagine.
Using an undocumented "feature" (properties of the baseURL result) can result in a brittle client that may fail in the future. Be careful of the siren-song of pre-mature optimization.
The baseURL value changes only when you move from different environments (i.e: DEMO vs PROD). I would encourage you to store/cache it yes. Keep in mind when your application is ready for PROD, you will want to get the baseURL for PROD and store/use that appropriately.
I am working on an iphone app which uses instagram API..and I would like to know the following things..Is it possible to get data from instagram without user logging?If so, what type of data would be retrieved from it?Is it possible to access data of a specified user?Or is it only possible using social networking sites like facebook,tumblr etc?
thanks
Yes, with a valid client id, you can fetch user information for a specific user id. Information available includes name, bio, website, and profile picture. You can also return multiple users' data using the search endpoint.
Take a look at the User Endpoints documented here: http://instagr.am/developer/endpoints/users/
I also suggest reading Do you need to authenticate? section here: http://instagr.am/developer/authentication/
NOTE: by providing a client id instead of a valid user token, you are counting against your own application's 5000 calls per-hour limit. If you plan on having a large user page, you would need to authenticate each user to avoid this limit.