Authentication

API Access Mechanism using OAuth2

OVERVIEW

HighQ uses OAuth2 for all API access. 


Methodology to get an access token using OAuth:

There are multiple steps required to obtain an access token. 


1) Client Registration


This step starts by obtaining a client ID and secret key from HighQ.

HighQ will register the client in our OAuth Server and provide you with a client ID and secret key. Please note that the generated token is valid for a specific time.

Note:

Collaborate OAuth token is generated per Collaborate instance and is not centralised for all Collaborate instances, hence the API application registration is specific to a Collaborate instance and is independent of any other Collaborate instance. 
The integrator using the API registration from one Collaborate instance will have to change the OAuth credentials if they want their API integration to work with another Collaborate instance.
Due to this OAuth architecture we suggest that the OAuth details be saved in a configuration file or are easily changeable through an interface, so that code recompile is not required for a generic solution.  


The format of the API client registration is as under:

client_id:1012

client_secret:dp3yp9zm6svZzUqduQH4CEYC2VgjwWLO


2) Generate a OAuth code 


Using the client specific details call the following URL using the web browser. The client_id and redirect_uri is to be replaced for each client.

The redirect_uri is the URI from where the REST calls will be instantiated. 

https://<instancename.highq.com>/<instancename>/authorize.action?response_type=code&client_id=1012&redirect_uri=http://www.highq.com/ 


This will generate a code and append it as query string tag to the end of the redirect URI after execution of the above URL. Please save this code for later steps. 
Please note that this code is only valid for 30 minutes, if you do not use this code within 30 minutes of generation, you will need to regenerate a fresh code.

Note: Please change the <instancename> to your own instance name. 


3) Generate an access token


The final step is to create an access token which will be used on each subsequent request. (We suggest you use an API Client like SoapUI to execute these methods.)

The following post request is to be made to the below URI with the correct method and content-type as listed below. Please replace the client_id, client_secret and code (obtained in the earlier steps).


method:post
content-type;application/x-www-form-urlencoded
URI: https://<instancename.highq.com>/<instancename>/api/oauth2/token
Post Body: grant_type=authorization_code&client_id=1012&client_secret=dp3yp9zm6svZzUqduQH4CEYC2VgjwWLO&code=d6jJodLD2F

A sample response will look like this:


<TokenResponse>
   <access_token>E_MIswtXKguKZ21h1RlueUXQqFvyTCxw</access_token>
   <expires_in>2419200</expires_in>  (In seconds)
   <refresh_token>nincFU9Jv86YRiX3rsvgPlsv6tAc0Nks</refresh_token>
   <token_type>bearer</token_type>
   <useremail>user@clientname.com</useremail>
</TokenResponse> 


This gives you the actual access_token 


4) Call the API endpoints


Once you have obtained the access token, you can call the API endpoints by setting the Auth-Type and Authorization request headers.

As an example you can try out the following call to get a list of Collaborate sites:

https://<domain url>/<instancename>/api/<api version number>/sites

Domain URI is the URI of your clients Collaborate instance

The instance name is the name given to your client's instance and it can be determined by calling your clients domain name. 

API version if the version of the API you want to use, this depends on the Collaborate version and an explanation is listed here

Auth-Type:OAUTH2

Authorization:Bearer <access_token> 

replace the <access_token> in the above header

 

Using the Refresh Token

 

Please read the managing token expiration details to ensure OAuth token management


The OAuth2 access_token expires after a given time, specified in the expires_in parameter. Before the token expires, refresh_token can be used to obtain a new access_token.

The following is the methodology to obtain a new access_token: 

METHOD:POST

Content-Type:application/x-www-form-urlencoded

URL:http://clientinstance.highq.com/clientinstance/api/oauth2/token

POST value:

client_id=C003&client_secret=7B4AA1AD-24F2-477B-857F-796CD5D0E04D&grant_type=refresh_token&refresh_token=6529d221d9bbca85fc0967562a544d58
 

{
    "token_type": "bearer",
    "expires_in": "31536000",
    "access_token": "jAfvL0rpBGKix16iecuxxxxxxxxxxxxx",
    "refresh_token_expires_in": "31536000",
    "refresh_token": "BKLZvP5XEIlPIGc_ruwTj7xxxxxxxxxxx",
    "useremail": "user@domain.com"
}


Useful links

1)http://oauth.net/2/
2)http://developers.box.com/oauth/

 

Comments


51 Comments

Wrong steps provided , in step 3 POST  BODY  we must provide the code generated in step 2  so the ideal body message will be grant_type=authorization_code&client_id=118&client_secret=Ps3C1ms7FmhRAoY0lH_RsD1GtVeMYoWJ&code=K5agMuKc8j  you have missed the code argument


I am repeating Rodrigo Flores's question in the hopes that there has been any progress in the last one and a half years, but would there be any way to access the Collaborate API with a system account, in order to get data from iSheets without having to get a passcode every single time? i.e. Something that would run on a server and pull into an on-premise SQL database.


Christopher Brown, there isn't, but there is a "sneaky" way:

Use the Get Sites endpoint to look for your (token's) My Site:

https://collaborate.highq.com/sitepoint/api/14/sites?filterby=all&name=My%20Site&limit=1

In the result set will be 1 site, where the siteowner is....

 

{
   "siteowner": {
      "firstname": "string",
      "lastname": "string",
      "email": "string",
      "userid": 0,
   }
}

You can then use the Get User API endpoint if you need more details about yourself.

NOTE: It's not infallible, for example, maybe some clever dick might actually create a site called "My Site". So perhaps you may want to increase the limit to 10, and filter the returning matched sites, looking for the property "mysite" === true, if you want to cover all bases...

Andrew


Is there a Token Info / introspection endpoint which returns the user details based on an access token ? I have a middle tier api which will need to validate HighQ user access tokens (since Open Id /claims etc approach isnt possible/supported). Id rather not implement this with the token+username against the user api.


Ha Nguyen Danh No, and you'll notice that there is no 'log in' endpoint either. If you are implementing 'logging in' and 'logging out' in your application (which consumes our API) you are, in effect, building an abstraction on top of the OAuth2 token flow. If you feel as though its really important that you 'break' any authentication between the services, when a user hits logout in your app, you could use the token revocation endpoint?



This Stack Overflow post explains it fairly nicely.


Well spotted Kristoffer Aurdal . 99% of API related requests we get in support are for Collaborate, so I hadn't actually realised that we use a different spelling here. Will ensure that the team are aware.


Thanks Peter! Seems that OAuth2 authentication is more aimed to client side apps.


Hi, is there a way to automatically login to HighQ? As I'm creating an integration through database to isheets using an ETL, ask user's login credentials does not makes sense.


Is there a reason why the refresh token response does not return an `expires_at` timestamp like the initial authentication response?


Is it possible to style the login page used in the OAuth2 flow, like you can style the regular login page?


Hi Ben Capps, yeah it is not possible to change authentication ways. We managed to implement a connection on ourselves when using the PowerBI Desktop client by writing code via the Query Editor (basically passing the access code in the header with the API call), but this does not work on PBRS as it is not taken into consideration upon periodically scheduled refreshs. At the moment we are looking into a workaround to utilize Azure functions as described in this post: https://medium.com/@thyejansman/refresh-any-oauth2-api-from-powerbi-online-dataflows-using-azure-functions-fe89f8ac95cf



Sorry for my late response I think I haven't received any mail from the system about your mention. Big coincedence I actually read this right now :-)


Jonathan Arndt Did you ever get a solution to this question or find an alternative?


Tomas Hlavaty, if you are on version 5.1, you could get HighQ to enable the Swagger documentation. It doesn't cover all the API endpoints (yet), but taking a look at, and executing, some of the REST points may give you a better feel for what is needed.

For example, once Swagger UI is enabled by HighQ:

  1. Load up the page and press the Authorize button to generate an API token.
  2. Find the get site list v2 endpoint (Ctrl + F, enter get site list into the Chrome search box.
  3. Open the panel and press the Try it out button
  4. Scroll down to the name parameter input box and enter My Site.
  5. Scroll down further and choose what format (response content type drop-down) you want the response to be: JSON or XML
  6. Press the Execute button.
  7. Down below is the curl statement, API url, and the response body
  8. In the response body look for "siteFolderID".  This will be the ID of the folder that holds your files (My Files).

The endpoint to retrieve the list of those files is not implemented yet in the Swagger UI, however, this would be the API endpoint you will call, where you would set the query parameter (q) to:

/api/2/files?q="folderid=n"

where n is the folder ID you received in siteFolderID above.

Hope this helps,

Andrew


ok, is there any example at all showing login requests + responses + a simple request using the api, for example listing my files?


is there a curl example showing for example login + list of my files?


@Lars-Erik Hobber if you keep on refreshing the token before it expires then you will not need to go through this process for generating a token.


Hi, is there a limit as to how many refresh tokens one can acquire before having to go through this process again?


Leo Furze-Waddock please try out the call, you will get the useremail attribute back. I have updated the documentation accordingly.


Is it correct the 'TokenResponse' for new access tokens includes a 'useremail' attribute, but the 'TokenResponse' for renewed access tokens does not?


I am not able to identify what is my instance name in step 2. It is required at 2 places in the url. I am trying to generate an OAuth Code.


Thank you for the update, much appreciated.


Andrew Quinn we have scheduled this improvement in Collaborate 4.3 currently under development. 4.3 is scheduled to be released in Q1 2018. The "Access Type" field is a HighQ Internal setting, apologies that it is being displayed to the system admins at the moment, we plan to hide this setting in the next major release.


Hi Imran Aziz, do you have an update on when the state key parameter will be supported now that we are at 4.1.6 (or 4.2 for non-MSSQL Enterprise instances)? Also, can the Knowledge Base (or similar) be updated to include a description of what the "Access Type" field, in the Register Application form, does. Thanks in advance, Andrew


Tom Clabon we are planning to pick up the state key parameter in 4.1.3 release, we plan to release 4.1.3 in June this year.


Hi. Any update on when the state key will be supported?

We've also noticed that the redirect_uri param for the authorize request can be any url and is not checked against the one configured for the application. Will this change at any point because as per the oauth spec it should be?

For our application, because of the missing state key we need the redirect_uri to not be checked so the current behaviour is fine. However, if we release and at some point in the future redirect_uri checking is enforced, then we'd require state key support and we would need to re-release and re-deploy at all our customers


Mukesh Singh thank you for your feedback. I am afraid we do not support the State parameter in our OAuth implementation at this time, however this is part of our roadmap and will be implemented in an upcoming release.


Hello HighQ, Another basic functionality but could not find in your example above. I noticed while generating Auth code you are only passing response_type, client_id, and redirect_uri. You are not using state parameter which is one of the essential part. I tried to pass the state parameter but the return url does not carry state parameter in query string.

Could you please confirm if HighQ supports "state" parameter.

 


Jim Page thank you for your comment  and explanation and glad to hear that you have been able to automate the process. Going forward we plan to provide an impersonation API, which can be used through a Collaborate system admin account to generate OAuth token for other users and then call the API methods on their behalf. This will enable the integrators to only generate the OAuth token once for a system account and then be able to impersonate other users in the system. 


A use case for our business is to make automated API calls without human intervention.  Unfortunately Step 2 (Generate OAuth Code) requires a web browser and a user to enter login details (so that security context can be set) and as such causes an issue with any automated / unmanned process.  For information, I have been investigating this and written an POC which uses browser automation to take the place of the human.  This does appear to work.


Hi Imran Aziz, in iSheet API, there is no end point to get data. Can you please tell me end point to make REST call.


Vikas Baweja  please raise a support ticket in our online support system, as that is the best place to address specific client issues. The 401 error message is generally only generated if the OAuth token is either invalid or has expired. Please provide all instance specific information in the support ticket, so that we can check in our logs as to what is going on. Thanks.  


Imran Aziz 401 error was when I am sending request using OAuth Access token, It worked for folder info and file download, but it didn't work for iSheet. I am accessing this as System admin. Do I need to have some other permission on iSheet? Let me know if you want me to email you my c# code? For whitelisting our IP, our system uses messagelabs, so IP changes every time I'll still check this our system engineer. I need to pull this data to local system for some urgent projects. Is there any way to organize a call?


Vikas Baweja  the API uses OAuth as its authentication mechanism, and the reason that your are getting 401 can be due to permissions issue. Please check that you have permissions to the specific isheet and the site that you are using in your query.  There are two XML feeds, the one that you are using requires a valid session so it is only going to work when you login to the system and create a valid session, there is a second XML feed which you can view for each isheet view by going into the edit mode. The URL looks like this https://{siteurl}/{instancename}/xmlExportLink.action?linkParam=blIffusw85%2BjjhvmI9khRFWsGUuddkcz4J5wsP4vzrVRCf5RG9GjVw%3D%3D . This XML feed works based on IP white list, which can be provided in admin settings ( For this you will need to raise a support ticket http://support.highq.com and the support team will add your IP address to the white list) 


Imran Aziz Thank you for the suggestions. One more question (hopefully), I need to export xml from an iSheet automatically so that I can then import the data from the isheet to another system, is it possible to make an API call to the isheet xml url? Thanks! 


Is it possible to automate the OAuth Code generation (step 2) programatically?


Hi, Generate a OAuth code is just one time or do I have to do everytime? I need to use API. I need to put a overnight job to pull data from iSheet. what's best way?

 

Last Updated: Nov 08,2024