<access-service>/api/v1/clientapps

URL structure

https://access-service.xy-company.com/api/v1/clientapps

Supported methods and overview

• POST - registers a new client application with the Cocoon Data Platform.
• GET - retrieves a list of information for all client applications currently registered on the Cocoon Data Platform.

Detailed description

This API endpoint serves a number of purposes:

• Registers a new client application with the Cocoon Data Platform for the purposes of configuring that client application's identity (as well as the applcation's Cocoon Data user authentication and authorization) with the Cocoon Data Platform via the OAuth 2.0 Authorization Framework.
• Retrieves a list of information about the OAuth 2.0 configuration of all client applications currently registered on the Cocoon Data Platform.

Supported roles

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

• SafeShare administrator

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

Required POST-request parameters

The following required parameters must be sent in the body of the POST request, as individual members of a JSON object:

• appName - The name for the new 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 client ID for this client application.
• clientSecret - The client secret for this client application.
• accessTokenValiditySeconds - The 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 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 ) - A 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", "implicit", "password", "refresh_token", "mfa" ],
    "refreshTokenValiditySeconds": 4838400,
    "registeredRedirectUris": "https://callback"
  }

Optional GET-request parameters

The following optional parameters can be sent in the URL of the GET request:

• limit - 0 to 100 (default is 0).
• offset - default is 0.
• orderBy - ASC or DESC (default is ASC).
• sortBy - .
  Example (reqeust):

  https://access-service.xy-company.com/api/v1/clientapps

Returns

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

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

• items ( from GET requests only ) - .
  • clientSecret - .
  • appName - .
  • authorizedGrantTypes - .
  • registeredRedirectUris - .
  • accessTokenValiditySeconds - .
  • refreshTokenValiditySeconds - .
  • enabled - .
  • idAsString - .
  • id - .
  • clientId - .
• count ( from GET requests only ) - .
• offset ( from GET requests only ) - .
  Example (response from GET request):

  {
      "items": [{
          "clientSecret": "androidClientSecret",
          "appName": "Cocoon Data Android Client",
          "authorizedGrantTypes": ["refresh_token", "authorization_code", "password", "device", "mfa"],
          "registeredRedirectUris": null,
          "accessTokenValiditySeconds": 600,
          "refreshTokenValiditySeconds": 604800,
          "enabled": true,
          "idAsString": "781",
          "id": "781",
          "clientId": "androidClient"
      }, {
          "clientSecret": "cocoondataWebAppSecret",
          "appName": "SafeShare Web Application",
          "authorizedGrantTypes": ["implicit", "refresh_token", "authorization_code", "mfa"],
          "registeredRedirectUris": "https://web.safeshare.cocoondata.com/#/auth",
          "accessTokenValiditySeconds": 600,
          "refreshTokenValiditySeconds": 86400,
          "enabled": true,
          "idAsString": "999",
          "id": "999",
          "clientId": "cocoondataWebApp"
      }, {
          "clientSecret": "exampleClientApplicationSecret",
          "appName": "Example Client Application",
          "authorizedGrantTypes": ["authorization_code", "implicit", "password", "refresh_token", "mfa"],
          "registeredRedirectUris": "https://callback",
          "accessTokenValiditySeconds": 2419200,
          "refreshTokenValiditySeconds": 4838400,
          "enabled": true,
          "idAsString": "772317323423203328",
          "id": "772317323423203328",
          "clientId": "exampleClientApplication"
      }, {
          "clientSecret": "mvcWebClientSecret",
          "appName": "Cocoon Data MVC Web Client",
          "authorizedGrantTypes": ["implicit", "refresh_token", "authorization_code", "password"],
          "registeredRedirectUris": null,
          "accessTokenValiditySeconds": 10000,
          "refreshTokenValiditySeconds": 10000,
          "enabled": true,
          "idAsString": "779",
          "id": "779",
          "clientId": "mvcWebClient"
      }, {
          "clientSecret": "osxClientSecret",
          "appName": "Cocoon Data OSX Client",
          "authorizedGrantTypes": ["refresh_token", "authorization_code", "password", "device", "mfa"],
          "registeredRedirectUris": "https://safe-share-oauth-redirect",
          "accessTokenValiditySeconds": 600,
          "refreshTokenValiditySeconds": 604800,
          "enabled": true,
          "idAsString": "780",
          "id": "780",
          "clientId": "osxClient"
      }, {
          "clientSecret": "safe-share-ios",
          "appName": "SafeShare iOS",
          "authorizedGrantTypes": ["refresh_token", "authorization_code", "password", "device", "mfa"],
          "registeredRedirectUris": "x-com-safe-share-ios://",
          "accessTokenValiditySeconds": 600,
          "refreshTokenValiditySeconds": 1209600,
          "enabled": true,
          "idAsString": "778",
          "id": "778",
          "clientId": "safe-share-ios"
      }, {
          "clientSecret": "secure-sync-secret",
          "appName": "SafeShare Windows",
          "authorizedGrantTypes": ["implicit", "refresh_token", "authorization_code"],
          "registeredRedirectUris": "https://docs.cocoondata.com/,https://docs.cocoondata.com/status",
          "accessTokenValiditySeconds": 600,
          "refreshTokenValiditySeconds": 1209600,
          "enabled": true,
          "idAsString": "777",
          "id": "777",
          "clientId": "secure-sync"
      }],
      "count": "7",
      "offset": "0"
  }