Skip to main content

​
URL structure

​
Supported methods and overview

  • POST - used to obtain for an access token (and optional refresh token) representing a Covata user (typically within an organization) using either the authorization code or password OAuth 2.0 grant types.

​
Detailed description

This API endpoint serves a number of purposes:
  • Completes authorization to obtain an access token (and optionally a refresh token) when using the OAuth 2.0 authorization code grant type.
  • Initiates a request for an access token (and optionally a refresh token) using the OAuth 2.0 password grant type grant type.

​
Required headers

The request’s header requires HTTP Basic authentication, whose value is the string value of your application’s client ID and client secret (separated by a colon) and encoded with Base64.
The client ID and client secret values constitute your application’s client credentials, which would have been generated when your application was registered on the Covata Platform. Also see Configuring client applications in the Safe Share Administrator’s Guide for more information.
For example, encoding:
  • exampleClientApplication:exampleClientApplicationSecret
    with Base64 results in the value:
  • ZXhhbXBsZUNsaWVudEFwcGxpY2F0aW9uOmV4YW1wbGVDbGllbnRBcHBsaWNhdGlvblNlY3JldA==
Therefore, the HTTP Basic authentication header would be:
  • Authentication: Basic ZXhhbXBsZUNsaWVudEFwcGxpY2F0aW9uOmV4YW1wbGVDbGllbnRBcHBsaWNhdGlvblNlY3JldA==
The request also requires form URL-encoded data in the body:
  • Content-Type: application/x-www-form-urlencoded

​
Required parameters

The following required parameter must be sent in the body of the request (as form URL-encoded data):
  • grant_type - The grant type used in the authentication and authorization request/s to the Covata Platform. Specify a value of:
    • password for the password grant type
      or
    • authorization_code for the authorization code grant type.

​
Grant type-specific parameters

In addition to the required parameters above, some of the following parameters are also required based on the grant type used and should be included in the body of the request (as form URL-encoded data):
  • code ( Required when using the authorization code grant type ) - The authorization code itself, which is retrieved in the response from the Covata Platform (i.e. following an initial request to <access-service>/api/oauth/authorize to initiate the process for obtaining an access token).
  • redirect_uri ( Required when using the authorization code grant type ) - The redirect URI that was submitted in the initial request to <access-service>/api/oauth/authorize to retrieve an access token. The value specified here is only used validate that it matches the redirect_uri value specified in this initial request.
  • username ( Required when using the password grant type ) - The email address of a Covata user’s credentials (acquired through your application).
  • password ( Required when using the password grant type ) - The password of a Covata user’s credentials (acquired through your application). Example (request parameters - using the password grant type):

​
Returns

A JSON-formatted response containing the following members:
  • access_token - The access token itself, as a JSON Web Token (JWT) value. The resources (i.e. API endpoints) of the Covata Platform that this access token grants permission to are based on the Covata user whose credentials were used for authentication, that user’s roles (explained in more detail in the Organization Administrator’s Guide) and if applicable to the API endpoint, the user’s:
    • membership of organizations and
    • ownership or collaborator status on files or folders.
  • token_type - The brief description for the type of token (above) - i.e. usually bearer.
  • refresh_token - The refresh token itself, as a universally unique identifier (UUID) value. This value will not be present if the configuration of your client application on the Covata Platform does not permit refresh tokens to be issued. See Registering your application on the Covata Platform for more information.
  • jti - The UUID value for the JWT access token issued in this response. This value is a unique ID for the JWT issued in this response and is also known as a JWT ID. Example (response):