- to which a Covata user account is permitted to access, and
- is represented by an access token (1) .
Working with OAuth 2.0 on the Covata Platform
The Covata API utilises the OAuth 2.0 Authorisation Framework to authenticate and authorise Covata user accounts securely to the Covata Platform. The OAuth 2.0 process (or ‘dance’) to obtain an access token (1) using the authorisation code grant type (2) consists of the following steps:- Your (client) application initiates a request for an authorisation code from the Covata Platform.
Note: The authorisation code is a short string/code, typically alphanumeric, whose purpose is to ensure that this step (and especially the following 2) are connected. - A Covata user authenticates themselves to the Covata Platform (directly) and if this is successful, the Covata Platform sends back an authorisation code to your application.
- Your application makes a subsequent request to the Covata Platform to receive an access token. This 2nd request contains the authorisation code and your application’s client credentials.
* When deciding on which of these grant types to implement in your client application, the authorisation code may provide more security or trust than password, in that a Covata user’s credentials are not specified directly through your client application when the user authenticates to the Covata Platform. This grant type decision would most likely amount to the level of trust that parties outside your organisation have in your application.
Registering your application on the Covata Platform
Before developing your application, you should consult your SafeShare administrator to begin the process of registering your application on the Covata Platform. After agreeing on the grant type(s) that your application will implement, your SafeShare administrator can proceed with your application’s registration process. Once your application is registered, your SafeShare administrator should securely issue you with client credentials (a client ID and client secret) to hard code into your application. These credentials are used to ‘authenticate’ your application to the Covata Platform. Be aware, however, that if your application is a native desktop/laptop, a mobile or a user agent-based application, then client credentials are less secure than they would be for a server-side web application (with properly implemented TLS). Therefore in these circumstances, your SafeShare administrator may allow you to generate your own client credentials. See Configuring client applications in the SafeShare Administrator’s Guide for more information.Overview of the OAuth 2.0 process
The following steps outline the Covata API OAuth 2.0 process for authenticating and authorising your application to access a Covata user’s resources on the Covata Platform:- Initiating authentication and authorisation (initiate the process for obtaining an access token and optional refresh token from the Covata Platform)
- Receiving the access token (the Covata Platform responds with the access token)
Initiating authentication and authorisation
The authentication and authorisation process begins by initiating appropriate requests to the Covata Platform to obtain an access token. The nature of these requests differs depending on one of the three supported OAuth 2.0 grant types your application has permission to use: Once the authentication and authorisation process is successful, an access token is returned to your application. Pass this token in subsequent requests to the Covata Platform to perform other interactions and activities through the Covata API.Using the authorisation code grant type
Step (1) To obtain an access token from the Covata Platform using the authorisation code grant type, make an initialGET method request to this API endpoint:
with the following URL parameters:
response_type- Use the valuecodeclient_id- The client ID of your application’s client credentials, which would have been generated when your application was registered on the Covata Platform.redirect_uri- Your application’s URL/URI, which will handle the initial response from the Covata Platform that contains the actual authorisation code. This initial response is sent after the user has successfully authenticated.
redirect_uri value above) to handle the authorisation code, whose value is the code URL parameter.
For example:
POST method):
with the following parameters sent as form URL-encoded (i.e. application/x-www-form-urlencoded) data in the request’s body:
grant_type- Use the valueauthorisation_codecode- The value of the authorisation code returned by the the Covata Platform (and initially handled by your application through the redirect URI).redirect_uri- Your application’s URL/URI that handled the initial response from the Covata Platform that contained the actual authorisation code.
exampleClientApplication:exampleClientApplicationSecret
with Base64 results in the value:ZXhhbXBsZUNsaWVudEFwcGxpY2F0aW9uOmV4YW1wbGVDbGllbnRBcHBsaWNhdGlvblNlY3JldA==
Submitting a cURL command like the one above with at least one
being automatically included in the request. Be aware that this header is required for the request to succeed.
-d option results in the following header: Content-Type: application/x-www-form-urlencoded being automatically included in the request. Be aware that this header is required for the request to succeed.
Using the implicit grant type
To obtain an access token from the Covata Platform using the implicit grant type, make a singleGET method request to this API endpoint:
with the following URL parameters:
response_type- Use the valuetokenclient_id- The client ID of your application’s client credentials, which would have been generated when your application was registered on the Covata Platform.redirect_uri- Your application’s URL/URI, which will handle the response from the Covata Platform that contains the access token itself. This response is sent after the user has successfully authenticated.
Using the password grant type
To obtain an access token from the Covata Platform using the password grant type, simply make a singlePOST method request to this API endpoint:
with the following parameters sent as form URL-encoded (i.e. application/x-www-form-urlencoded) data in the request’s body:
grant_type- Use the valuepasswordusername- The email address of a Covata user’s credentials (acquired through your application).password- The password of a Covata user’s credentials (acquired through your application).
exampleClientApplication:exampleClientApplicationSecret
with Base64 results in the value:ZXhhbXBsZUNsaWVudEFwcGxpY2F0aW9uOmV4YW1wbGVDbGllbnRBcHBsaWNhdGlvblNlY3JldA==
Submitting a cURL command like the one above with at least one
being automatically included in the request. Be aware that this header is required for the request to succeed.
-d option results in the following header: Content-Type: application/x-www-form-urlencoded being automatically included in the request. Be aware that this header is required for the request to succeed.
Receiving the access token
From authorisation code or password grant type requests
Once the authentication and authorisation processes for either the authorisation code or password grant type above is successful (via the finalPOST method request to the <access-service>/api/oauth/token API endpoint), the Covata Platform responds with an access token in the body of the response (as a JSON object) as well as a refresh token (if your registered client application on the Covata Platform has been configured to issue one).
Example response:
From implicit grant type requests
Once the authentication and authorisation process for the implicit grant type above is successful (via theGET method request to the <access-service>/api/oauth/authorise API endpoint), the Covata Platform responds by redirecting to your application’s URL/URI (i.e. the redirect_uri value above) with an access token as a URL parameter (amongst other parameters).
Example response:

