<access-service>/api/oauth/authorize

URL structure

https://access-service.xy-company.com/api/oauth/authorize

Supported methods and overview

• GET - used to initiate the process for obtaining an access token (and optional refresh token) using either the authorization code or implicit OAuth 2.0 grant types.

Detailed description

This API endpoint initiates the process for obtaining an access token using either authorization code or implicit OAuth 2.0 grant types.

If the client application has been configured on the Covata Platform to issue refresh tokens, then a refresh token will accompany the access token. However, regardless of this configuration, refresh tokens are never issued when using the implicit grant type.

Required parameters

The following required parameters must be sent in the URL of the request:

• response_type - For the authorization code grant type, specify the string value code or for the implicit grant type, specify token.
• client_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 for the:
  • authorization code grant type, will handle the initial response from the Covata Platform that contains the actual authorization code. This initial response is sent after the user has successfully authenticated.
  • implicit grant type, will handle the response from the Covata Platform that contains the access token itself. This response is sent after the user has successfully authenticated.
  Example (request - using the authorization code grant type):

  https://access-service.xy-company.com/api/oauth/authorize?response_type=code&client_id=exampleClientApplication&redirect_uri=https%3A%2F%2Fmy-application-url%2Fauthcallback

This request results in The Covata Platform presenting the user with the Covata Sign-in page.

Returns

Once the Covata user (typically within an organization) has successfully authenticated, the Covata Platform responds by redirecting to your application's URL/URI (i.e. the redirect_uri value above), whose following URL parameters depend on the grant type used:

• code ( Authorization code grant type only ) - The authorization code value.
• access_token ( Implicit grant type only ) - 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, this 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 ( Implicit grant type only ) - The brief description for the type of token (above) - i.e. usually bearer.
• scope ( Implicit grant type only ) - .

• jti ( Implicit grant type only ) - The UUID value for the returned JWT access token. This value is a unique ID for the returned JWT, which is also known as a JWT ID.

  Example (response/redirect - using the authorization code grant type):

  https://my-application-url/authcallback?code=lEQmsFkB02NGPaB3YtaDnA