API Documentation
Toggle TOC panel
<access-service>/api/v1/clientapps/{clientInfoId}

URL structure

1 https://access-service.xy-company.com/api/v1/clientapps/{clientInfoId}

where {clientInfoId} is the ID for the client application's configuration information.

Supported methods and overview

  • GET - retrieves information about a registered client application (specified by clientInfoId).
    Note: The clientInfoId value is an ID that relates to the client application's configuration information/details on the Cocoon Data Platform and should not be confused with the client ID value.
  • PUT - modifies the fields of a registered client application (specified by clientInfoId).
  • DELETE - deletes a client application (specified by clientInfoId).

Note: The GET and DELETE methods take no parameters.

Detailed description

This API endpoint serves a number of purposes:

  • Retrieves a list of field information about the OAuth 2.0 configuration of a registered client application (specified by clientInfoId).
    The configuration information ID of the required client application can be obtained by calling the GET method of the <access-service>/api/v1/clientapps API endpoint, which retrieves a list of field information for all client applications on the Cocoon Data Platform.
    Tip: All information returned in the response from a GET method call to this API endpoint is also returned in the response from a GET method call to the <access-service>/api/v1/clientapps endpoint. Therefore, there is no need to call the GET method on this API endpoint (if you do not already have the client application's configuration information ID).
  • Modifies the fields of a registered client application (specified by clientInfoId). Only certain fields are required/used based on the values specified for the authorizedGrantTypes field.
  • Deletes a registered client application (specified by clientInfoId) from the Cocoon Data Platform. A Cocoon Data user account with the SafeShare administrator role would need to re-register this client application again (using the <access-service>/api/v1/clientapps API endpoint) to allow this client application to access the Cocoon Data Platform's resources again.
    Note: This feature is not available in SafeShare Administration (i.e. through the 'Client Applications' configuration page).

Supported roles

This API endpoint supports the following Cocoon Data user roles (as described in the SafeShare Administrator's Guide):

The Cocoon Data Platform's resources available to a Cocoon Data user meeting the criteria above is determined by the access token submitted in the header of requests to this endpoint.

Required headers

The appropriate access token as the Bearer token:

  • Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

The following header is required if the body of the request has a JSON object:

  • Content-Type: application/json

Optional parameters

The following optional parameters can also be sent in the body of the PUT request, each as individual members of a JSON object:

  • appName - The updated name for the client application which will appear to Cocoon Data users (when they attempt to authenticate to the Cocoon Data Platform from this client application).
  • clientId - The updated client ID for this client application.
  • clientSecret - The updated client secret for this client application.
  • accessTokenValiditySeconds - The updated number of seconds that an access token issued by the Cocoon Data Platform to this client application is valid for.
  • authorizedGrantTypes - An array of elements, each of which is an enumeration (enum) value representing a grant type (also known as authorization grant) that the Cocoon Data Platform will permit this client application to use to issue the application with an access token. Valid values include:
    • authorization_code - An OAuth 2.0 grant type best suited for client applications that are server-side web applications, native desktop/laptop or mobile device applications. See Authorization Code in the Grant type details section/table of the SafeShare Administrator's Guide for more information.
    • implicit - An OAuth 2.0 grant type best suited for client applications that are user agent-based applications, such as one that runs client-side in a web browser. However, this grant type does not support the use of refresh tokens. See Implicit in the Grant type details section/table of the SafeShare Administrator's Guide for more information.
    • password - An OAuth 2.0 grant type best suited for client applications that are native desktop/laptop or mobile device applications, or administrator/system-run services, such as a scheduled job. See Password in the Grant type details section/table of the SafeShare Administrator's Guide for more information.
    • refresh_token - An option (supporting the OAuth 2.0 grant types above) that determines if the Cocoon Data Platform can issue refresh tokens to this client application, which the application can then use to request for new access tokens.
    • mfa - An option (supporting the OAuth 2.0 grant types above) that determines if the Cocoon Data Platform will permit this client application to support Cocoon Data users authenticating with 2FA enabled.
      Note: This feature is not available for selection in SafeShare Administration (i.e. through the 'Client Applications' configuration page) and does not appear anywhere throughout the user interface of SafeShare Administration. However, when configuring a client application through SafeShare Administration, this option is always automatically chosen.
    • device - An option (supporting the OAuth 2.0 grant types above) that determines if the client application (running on a specific device - typically on a mobile device platform such as iOS or Android) can authenticate a specific Cocoon Data user with a passcode.
  • refreshTokenValiditySeconds ( only required when authorizedGrantTypes includes refresh_token ) - The updated number of seconds that a refresh token issued by the Cocoon Data Platform to a client application is valid for. This value must be greater than the accessTokenValiditySeconds value above.
  • registeredRedirectUris ( only required when authorizedGrantTypes includes authorization_code and/or password ) - An updated list of one or more valid Uniform Resource Identifiers (URIs) which the Cocoon Data Platform uses to verify the value of the redirect URI (also known as a redirection endpoint) parameter sent by the client application to the Cocoon Data Platform (during an OAuth 2.0 authentication and authorization request to obtain an access token).
    Example (request):
    {
    "appName": "Example Client Application",
    "clientId": "exampleClientApplication",
    "clientSecret": "exampleClientApplicationSecret",
    "accessTokenValiditySeconds": 2419200,
    "authorizedGrantTypes": [ "authorization_code", "password", "refresh_token", "mfa", "device" ],
    "refreshTokenValiditySeconds": 4838400,
    "registeredRedirectUris": "https://callback"
    }

Returns

If the request succeeded, then an HTTP response status 200 OK is returned.

For successful GET and PUT requests only, a JSON-formatted response containing the following members is also returned:

  • clientSecret - .
  • appName - .
  • authorizedGrantTypes - .
  • registeredRedirectUris - .
  • accessTokenValiditySeconds - .
  • refreshTokenValiditySeconds - .
  • enabled - .
  • idAsString - .
  • id - .
  • clientId - .
    Example (response):
    {
    "clientSecret": "exampleClientApplication",
    "appName": "Example Client Application",
    "authorizedGrantTypes": ["authorization_code", "password", "refresh_token", "mfa", "device"],
    "registeredRedirectUris": "https://callback",
    "accessTokenValiditySeconds": 2419200,
    "refreshTokenValiditySeconds": 4838400,
    "enabled": true,
    "idAsString": "772622283570610176",
    "id": "772622283570610176",
    "clientId": "exampleClientApplication"
    }