<access-service>/api/oauth/authorize

URL structure

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

Supported methods and overview

• GET - initiates 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.

When using the implicit grant type, the access token itself is returned in the response to this API endpoint. (All other grant types return their access tokens in calls to the <access-service>/api/oauth/token endpoint.)

If the client application has been configured on the Cocoon Data 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 Cocoon Data Platform.
• redirect_uri - Your application's URL/URI, which for the:
  • authorization code grant type, will handle the initial response from the Cocoon Data 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 Cocoon Data 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 Cocoon Data Platform presenting the user with the Cocoon Data Sign-in page.

If the client application requesting this API endpoint was developed by a third party (i.e. a non-Cocoon Data client application), then an additional page is presented requesting the user to approve the client application access to the user's resources on the Cocoon Data Platform. This step is known as the application approval step and only needs to be performed once (unless this approval is subsequently revoked by the user).

Returns

Once the Cocoon Data user has successfully authenticated (and if required, has accepted the application approval step), the Cocoon Data 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 Cocoon Data Platform that this access token grants permission to are based on the Cocoon Data user whose credentials were used for authentication, this user's roles (explained in more detail in the Organisation Administrator's Guide) and if applicable to the API endpoint, the user's:
  • membership of organisations 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