<access-service>/api/v1/objects

URL structure

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

Supported methods and overview

• GET - retrieves information about the active version of a file object/Secure Object using the SHA-512 value of its encrypted data.

Detailed description

This API endpoint retrieves information about the active version of a file object using the SHA-512 hash value of its encrypted data (i.e. matching the SHA-512 value recorded in the file object upon its completion).

Notes:

• This API endpoint is only available if the Cocoon Data user (whose access token is submitted in the request to this endpoint) has access to this file object (as either the owner of or a collaborator on this file).
• The SHA-512 value specified in the request must match that of SHA-512 value recorded in the file object (upon the file object's completion), because for every time a given piece of data is encrypted (i.e. using AES), the SHA-512 of the encrypted data will be different.

Supported roles and conditions

This API endpoint supports requests utilizing Cocoon Data user accounts with the following roles (as described in the Organisation Administrator's Guide) and conditions:

• Originator - when this user owns the file object.
• Originator, Collaborator and Ad hoc - when this user is a collaborator on the file object.
  Note: If this user also has the View Other permission on the file object, additional information is returned in the response.

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...

Required parameters

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

• sha512 - The unique SHA-512 hash value of the encrypted data associated with the file object, which the Cocoon Data user (whose account's access token was used to call this API endpoint) owns or is a collaborator on. See Supported roles and conditions above for details.
  Example (request):

  https://access-service.xy-company.com/api/v1/objects?sha512=0X3iJ2keHhOBzrdJmUCw2QO0r7OOAwtaWDHGKU5cnkHVhdjeWtyvQAjjwAigT2dakgtM/BeZ/qvjuwAUtG9FdA==

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:

• id - The ID value of the file object.
• shareStartTime - The date and time from which collaborators on this file object can begin accessing the file's content. This value is null if the shareStartTime was never specified when the file object was initialized or created, or last updated.
• shareEndTime - The date and time from which collaborators' access to this file object's content ceases. This value is null if the shareEndTime was never specified when the file object was initialized or created, or last updated.
• shared - A boolean value that indicates whether or not the file object has been shared with any collaborators.
• name - The name of the file object, which was set when the file object was initialized or created, or last updated. This value is null if the name was never specified.
• sha512 - The unique SHA-512 hash value of the encrypted data associated with this Created/complete file object. This value should match that of the sha512 parameter value submitted in the request to this API endpoint.
• owner - A member containing information about the Cocoon Data user who is the current owner of the file object. This member contains the following sub-members:
  • email - This email address of the Cocoon Data user who owns this file object.
  • firstName - The first name set by this Cocoon Data user. This is the first name that appears on the Users page of SafeShare Organisation Administration and the My Account feature of Cocoon Data SafeShare for Web.
  • lastName - The last name set by this Cocoon Data user. Like the first name (above), this appears on the User page of Organisation Administration and the My Account feature of SafeShare for Web.
  • mfaEnabled - A boolean value that indicates whether or not two-factor authentication has either been set by this Cocoon Data user on their own account, or enforced for all members of the organisation (by an Organisation administrator).
  • id - The ID of this Cocoon Data user's account.
  • accountType - A member containing the internationalization (I18N) property key/code ^* for the account type, including the account type's value (i.e. hard-coded in the Cocoon Data Platform), as sub-members:
    • i18n - A member containing the I18N code ^* for the account type as sub-members:
      • code - The I18N code for the account type's value, beginning with server.useraccounttype. This I18N code could include the substring local, ldap or external.
      • arguments - An array containing any arguments/variables that constitute the value of the I18N code above. Since none of the account types' values contain any variables, this array is always empty.
    • value - The value of accountType as it is hard-coded in the Cocoon Data Platform. Your client application can exploit this value (instead of i18n above) if I18N is not required.
    ^* Your client application can exploit the Cocoon Data Platform's I18N features, by initially downloading the relevant language bundles (from the the Cocoon Data Platform), then using the i18n code (and if applicable, arguments) values above to extract the property values derived from these language bundles for use in your client application. For more information about the Cocoon Data Platform's I18N features, see Managing internationalization in the SafeShare Administrator's Guide.
    Note: For more information about account types, see the description for Account Type in the Organisation Administrator's Guide.
• hasView - A boolean value that indicates whether or not the Cocoon Data Platform's Content Service has generated a read-only view of the file object's data in storage.
  Notes:
  • The Content Service automatically sets this value to true after it sets the value of canGenerateView (below) to true and the Content Service has successfully generated and stored a read-only view of the file object's data.
  • If your client application is managing its own file data (i.e. the data is not being uploaded to the Content Service), then your application can exploit this element's value for any purpose.
• canGenerateView - A boolean value that indicates whether or not the Content Service is capable of generating a read-only view of the file object's data, which is based on the file name extension of the original file that was encrypted (as specified in name). For more information, see File formats supported by the content viewer in SafeShare for Web User's Guide.
  Notes:
  • Assuming the file name extension is one that supports a view being generated, the Content Service then automatically sets this value to true after the file object's data has been successfully uploaded and stored and the size of this data is less than the maximum configured file size for generating a view (i.e. 20 MB by default).
  • If your client application is managing its own file object data (i.e. the data is not being uploaded to the Content Service), then your application can exploit this element's value for any purpose.
• extension - The file name extension which appears after the final period/full-stop of the file object's name.
• organisation - A member containing information about the organisation in which this file object was created. This member contains the following sub-members:
  • name - The name of the organisation.
  • description - The description of the organisation, which can be set by Organisation administrators.
  • mfaEnabled - A boolean value that indicates whether or not two-factor authentication has been enforced for all members of the organisation.
  • id - The ID of the organisation.
• permissions - An array listing the individual permissions that the owner above or one of the collaborators below (whose access token was used in the request to this endpoint), has inherited from the location represented by parentId.
  Note: A bug in this version of the Cocoon Data Platform results in this property always returning an empty array in any requests to this endpoint.
• mimeType - The MIME type of the data associated with the file object, which was set when the file object was initialized or created, or last updated. This value is null if the mimeType was never specified on this file object.
• contentSize - The amount of space (in bytes) of the file object's data (as recorded by the Cocoon Data Platform's Access Service).
• parentId - The ID of the folder/collection that contains the file object. A value of 0 indicates that this file object is located at the logical root location.
• originator - A member containing information about the Cocoon Data user whose account was used to create this file object. This member contains the equivalent email and id sub-members only of either the owner member (above) or a collaborators array element (below). If these sub-members originally match those of the file's initial owner member and then the file's ownership changes to that of another Cocoon Data user, the owner member's email and id values will change while the equivalent sub-member values of this originator member will remain unchanged.
• state - The I18N code for the current state of the file object. This I18N code could include the substring incomplete for an initialized file object, created for a completed file or deleted for a deleted file.
• modifiedAt - The date and time when the file object was last modified. When a file object is initialized or created, this date and time should match (or be close to) that of the createdAt value below. Otherwise, if the file object has since been modified, this date and time should reflect when the file object was last modified.
• createdAt - The date and time when the file object was first initialized or created, either in its Incomplete or Created states.
• labelName - The name of the classification applied to the file object. Like labelId below, if this element's value is null, then no classification was specified (i.e. the labelId parameter was specified with an empty string or this parameter was omitted) when the file object was initialized or created, or last updated. This means that no classification restrictions (i.e. checks on Cocoon Data users' group membership and the association of these groups with individual classifications - see User group endpoints for more information) have been placed on collaborators added to this file object.
• type - Indicates object, which in turn indicates that information about item returned from this request is about a file object.
• labelId - The ID of the classification applied to the file object. If this element's value is null, then no classification was specified (i.e. the labelId parameter was specified with an empty string or this parameter was omitted) when the file object was initialized or created, or last updated.
• collaborators - An array containing information about each Cocoon Data user who is currently a collaborator on this file object. Each element of this array contains information about one of these Cocoon Data users and is represented as an object, containing the following members:
  • shareParentId - Indicates either a value of null or 0. A value of null indicates that the file object's location in its hierarchy of folders (e.g. as indicated in a SafeShare application's list of items) are equivalent between this collaborator (i.e. another Cocoon Data user account) and the current owner of this file object. A value of 0 indicates that the file object is being shared from the logical root file area/location of this collaborator's account. In SafeShare applications, this occurs when the owner of this file object has shared the file object with this collaborator, but the file object's parent folder has not also been shared with this collaborator.
  • shareName - Reserved for future use. Currently, this returns the value null.
  • permissions - An array listing the permission set applied to this collaborator (or inherited by them from the location represented by parentId) on this file object, along with the individual permissions that constitue this permission set.
  • email - The collaborator's email address.
  • firstName - The collaborator's first name. This is the first name that appears on the Users page of SafeShare Organisation Administration and the My Account feature of Cocoon Data SafeShare for Web.
  • lastName - The collaborator's last name. Like the first name (above), this appears on the User page of Organisation Administration and the My Account feature of SafeShare for Web.
  • id - The ID of the collaborator's Cocoon Data user account.
  Note: Only an empty array is returned from Cocoon Data user accounts who are collaborators on this file object and do not have the View Other permission on it.
  Example (response):

  {
      "id": "734242448553197568",
      "shareStartTime": null,
      "shareEndTime": null,
      "shared": true,
      "name": "Executive Report.pdf",
      "sha512": "0X3iJ2keHhOBzrdJmUCw2QO0r7OOAwtaWDHGKU5cnkHVhdjeWtyvQAjjwAigT2dakgtM/BeZ/qvjuwAUtG9FdA==",
      "owner": {
          "email": "alex.originator@xy-company.com",
          "firstName": "Alex",
          "lastName": "Originator",
          "mfaEnabled": false,
          "id": "732856217122553856",
          "accountType": {
              "i18n": {
                  "code": "server.useraccounttype.local",
                  "arguments": []
              },
              "value": "LOCAL"
          }
      },
      "hasView": false,
      "canGenerateView": true,
      "extension": "pdf",
      "organisation": {
          "name": "XY Company",
          "description": "",
          "mfaEnabled": false,
          "id": "732855142835470336"
      },
      "permissions": [],
      "mimeType": null,
      "contentSize": "3596924",
      "parentId": "0",
      "originator": {
          "email": "alex.originator@xy-company.com",
          "id": "732856217122553856"
      },
      "state": "server.object.states.created",
      "modifiedAt": "2016-07-19T02:58:55.534Z",
      "createdAt": "2016-07-19T02:57:21.300Z",
      "labelName": null,
      "type": "object",
      "labelId": null,
      "collaborators": [{
          "shareParentId": null,
          "shareName": null,
          "permissionSet": null,
          "email": "chris.collaborator@xy-company.com",
          "firstName": "Chris",
          "lastName": "Collaborator",
          "id": "732856277868658688"
      }]
  }