Authentication

Adding a new API application registration

OVERVIEW

In order to use the Collaborate API, an API application registration is required.  (Please note that the API is enabled by default but can be disabled at the instance level. If you do not see the API application registration option in system admin then please email support@highq.com to enable the API for your instance.)

A new API application registration can be found within the system admin interface accessed by the system administrators. 

The steps are: 

Navigate to Collaborate System administration and then choose API application registration. Click on Add application to create a new application registration.

Adding a new API application registration

Fill out the fields in the Application registration to create a new application registration.

  • All fields marked with asterisk * are mandatory and must be completed
  • The Secret key is generated automatically but you can generate it again by clicking on "Generate key". This key is critical, once you create the application registration you will need to use this client ID and secret key to generate the OAuth token. 
  • Redirect URL is the URL to which the OAuth code will be generated, this can be used to limit how the OAuth code is generated and is for added security.  This value can also be used to redirect the code generated to a desktop application rather than a web URL. 
  • The token expiration time can be used to set the time after which the generated OAuth token will expire and the client will need to use the refresh token to create a new OAuth token. 
  • Status field can be used to archive the application registration in case there is a security breach or some other cause of shutting down the clients using the particular application registration. 
  • The Show allow/deny screen option can be used to display the authorisation screen after the user logs into Collaborate to generate the OAuth token. This screen can prevent users from accepting the API token generation accidentally when they have a valid Collaborate session. 
  • The Application rate limit settings and Access type fields are not visible to system admin and are managed by HighQ.

Click Save to save the new application registration. 

Once saved, you can use the generated Client ID and Secret key for this application registration to generate the new OAuth token. 

 

Comments


4 Comments


Ha Nguyen Danh 



To extemporize on the workaround I use for programs which need to run 'unattended' , I create an .INI file, which basically describes the data you get from an initial token call:



[AUTH]

access_token = REDACTED_your_token_here

access_expiry = 2592000

refresh_token= REDACTED_your_token_here

refresh_expiry = 2628000

token_type = bearer

user = peter.simpson@highq.com



When my application runs, it checks to see if there is a 'database'* containing a value (I store the token as a singleton object). If there is not: it reads from the .ini file and stores the token and its metadata. If there is: we disregard the .ini



In order to keep the persisted token up to date, I create some token handling logic, which checks if a token is valid (it works out if its expired or not). If it is: it returns the token to be used by the code, if it isn't: it makes a refresh token call and updates the singleton object in my 'database'.



The longest an access token is valid for is 1 month and the longest the refresh expiry is 1 year, so providing that your process runs more frequently than once a year, it never runs into authentication issues. I have kept scripts going for well over a year using this approach.



* I'm using the term database VERY liberally here. At worst, this is just writing to a file, at best... its actually been a sqlite3 database.


Ha Nguyen Danh No other options here, we only support OAuth2 Authentication Code flow. There is no way of initially generating an access token without the code, and you can only get a code by delegation from the allow/deny screen.



The usual workarounds are: 1) create a web front end for your processes, or 2) to only have your process encapsulate the refresh token part of the workflow (which can be done without the code), and then you seed some storage that your application can access with an initial token.


Peter Simpson What types are supported in the Access Type field? Is there something like "Client Authentication" type that only require clientid and client secret and does not require human interaction when getting token?

We have a need as we will have some background process to make call to API

Last Updated: Jun 09,2023