<access-service>/api/v1/objects/{objectId}

​

URL structure

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

​

Supported methods and overview

• GET - retrieves information about file object/Secure Object (specified by objectId) ¹ .
• PUT - modifies the properties of a file object (specified by objectId). This involves the file’s owner or a collaborator with sufficient permissions on the file ² , performing any combination of the following:
  1. Modifying the collaborators (as well as their permission sets) on the file object.
  2. Modifying the classifications and time/date controls on the file object.
     Note: A collaborator with the Share permission on the file object (applied via the Manage permission set) can perform these actions (i.e. both 1 and 2) above.
  3. Renaming and/or moving the file object.
     Note: A collaborator with the Rename and Move permissions on the file object (applied via the Modify or Manage permission sets) can perform these actions.
  4. ( Deprecated ) Completing an Incomplete file object (which changes its state to Created). Only the file object’s owner can perform this action.
     Note: Use the <content-service>/api/v1/objects/{objectId}/contents endpoint for this purpose.
• DELETE - removes a file object (specified by objectId) to its owner’s Recycle Bin (known as ‘recycling’), which changes the file object’s state to Recycled. This can be performed by the file’s owner or a collaborator with sufficient permissions on the file ² .
  Notes:
  • A collaborator with the Remove (File) permission on the file object (applied via the Modify or Manage permission sets) can perform these actions.
  • Calling the DELETE method on a file object whose state is Incomplete (see <access-service>/api/v1/organisations/{orgGroupId}/objects for more information), deletes this file object immediately (i.e. without the file object being removed to the Recycle Bin).

​

Detailed description

• Retrieves information about a file object (specified by objectId). A file object’s ID can be obtained using one of the following API endpoints:
  • <access-service>/api/v1/organisations/{orgId}/items - retrieves a list of information associated with file objects in an organisation, which can be filtered using a variety of search criteria.
  • <access-service>/api/v1/organisations/{orgGroupId}/objects - retrieves a list of high-level information associated with all file objects that have been created within an organisation (available to Organisation administrators only), which can also be filtered using more restricted search criteria.
  • <access-service>/api/v1/objects - retrieves information about a file object using the SHA-512 value of its encrypted content.

• Allows a file object’s owner or a collaborator with sufficient permissions on the file ² to modify any combination of the following properties of the file object (specified by objectId):
  • Collaborators and their permission sets (specified through this endpoint’s collaborators parameter) - where a permission set is specific to each individual collaborator. For each collaborator, one of the following four permission sets can be applied:
    • View - grants the collaborator the individual View permission to allow the file’s ³ :
      • content to be viewed from a SafeShare application’s content viewer, as well as the
      • read-only view to be downloaded (via the GET method on the <content-service>/api/v1/objects/{objectId}/view endpoint).
    • Download - grants the collaborator the individual View permission (provided by the View permission set), as well as the following additional permissions to:
      • Download the file’s actual content ³ (via the GET method on the <content-service>/api/v1/objects/{objectId}/contents endpoint).
      • Print the file’s content ³ from a SafeShare application’s content viewer.
    • Upload - grants the collaborator the individual permissions provided by the Download permission set, as well the following additional permissions to:
      • Upload a new version of the file and its actual content (via the POST method on the <content-service>/api/v1/objects/{objectId}/versions endpoint), through the Upload File permission.
      • Access more information/properties about the file’s collaborators, through the View Other permission.
    • Modify - grants the collaborator the individual permissions provided by the Upload permission set, as well as the following additional permissions to perform any of these actions on this file object and/or its content (in the owner’s storage space):
      • Rename the file (via this endpoint’s name parameter). The Rename permission also provides access to a file’s other versions, which includes the ability to perform any of the following actions:
        • Retrieve information about all existing versions of the file (via the GET method on the <access-service>/api/v1/objects/{itemId}/versions endpoint).
        • Download the read-only view of any version of the file (via the GET method on the <content-service>/api/v1/versions/{versionId}/view endpoint).
        • Download the actual content of any version of the file (via the GET method on the <content-service>/api/v1/versions/{versionId}/contents endpoint).
        • Set another version of the file to be active (via the PUT method on the <access-service>/api/v1/objects/{itemId}/versions/{versionId} endpoint).
        • Permanently delete a version of the file other than the active one (via the DELETE method on the <access-service>/api/v1/objects/{itemId}/versions/{versionId} endpoint).
      • Remove the file (including all of its versions) to the Recycle Bin (via the DELETE method on this endpoint), through the Remove (File) permission.
      • Move the file to a different folder within a common folder hierarchy (via this endpoint’s parentId parameter). A common folder hierarchy is a folder hierarcy that contains this file, in which the same collaborator has also been added (with either the Modify or Manage permission set) to a higher level (i.e. a common) folder, such that this higher level folder forms the top of the folder’s hierarchy.
    • Manage - grants the collaborator the individual permissions provided by the Modify permission set, as well as the following additional permissions to perform any of these actions on this file object and/or its content (in the owner’s storage space):
      • Share the file with other collaborators (via this endpoint’s collaborators parameter), which also includes the ability to modify the labelId, shareStartTime and shareEndTime parameters (described next).
  • Classification (specified through this endpoint’s labelId parameter) - defines which groups of Covata users can be shared the file.
  • Time/date controls (specified through this endpoint’s shareStartTime and shareEndTime parameters) - the time and date from which all collaborators on the file can begin accessing the file object and its data and/or when this access ceases.
  • Name (specified through this endpoint’s name parameter) - the new name of the file.
  • Parent folder/collection (specified through this endpoint’s parentId parameter) - the folder to which the file will be moved.
• ( Deprecated ) Allows a file object’s owner ² to complete an Incomplete file object (specified by objectId), which changes its state to Created, by associating the SHA-512 value of the file’s encrypted data (specified through this endpoint’s sha512 parameter). (Be aware that this data must have been encrypted locally - i.e. not via server-side encryption by the Content Service). For more information about initializing an Incomplete file object, see <access-service>/api/v1/organisations/{orgGroupId}/objects.
  Note: Associating the SHA-512 value of a file object’s encrypted data through this endpoint is now a deprecated approach. Instead use the <content-service>/api/v1/objects/{objectId}/contents endpoint for this purpose.

• Owner is a Covata user whose account’s access token was used in initializing or creating the file object (bearing in mind that a file object’s ownership can subsequently be changed to that of another Covata user).
• Collaborator is a Covata user whose account has already been added as a collaborator to this file object (with a given permission set).

• Removes a file object (specified by objectId) to its owner’s Recycle Bin (known as ‘recycling’), which changes the file object’s state to Recycled.

​

Supported roles and conditions

• Originator - using the GET, PUT and DELETE methods, when this user owns the file object whose ID is specified by {objectId} in the request’s URL.
• Originator, Collaborator and Ad hoc - using the:
  • GET and PUT methods, when this user is a collaborator on the file object whose ID is specified by {objectId} in the request’s URL. For the PUT method, such a collaborator user can set the:
    • contentSize and/or sha512 parameters, when this user has the Upload File permission on this file object.
    • mimeType and/or name parameters, when this user has the Rename permission on this file object.
    • parentId parameter, when this user has the Move permission on this file object.
    • collaborators, labelId, shareStartTime and shareEndTime parameters, when this user has the Share permission on this file object.
      
  • DELETE method, when this user is a collaborator with the Remove (File) permission on the file object whose ID is specified by {objectId} in the URL.

​

Required headers

• Authorisation: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

• Content-Type: application/json

​

Optional PUT-request parameters

• collaborators ( For collaborator users as opposed to owners, requires the Share permission on objectId ) - A parameter containing the following optional sub-element parameters that relate to the collaborators being applied to this file object:
  • list - An array of elements about each collaborator, where each element of this array contains the following optional sub-elements:
    • email - The email address of the person to add as a collaborator to the file object. (This sub-element is optional, although omitting it serves no purpose.)
    • permissionSet - The permission set to apply to this collaborator. To apply a permission set to this collaborator, specify its ID as a sub-element parameter of this parameter:
      • id - The ID of the permission set. This ID can be obtained by calling the <access-service>/api/v1/permissions/sets API endpoint.
      Note: If this sub-element is omitted, then the View permission set is automatically applied to this collaborator.
  Additional note: It is worthwhile your client application storing these set of collaborators and their respective permission sets (e.g. in its own object) because any modifications to one or more collaborators on a file object (through this parameter) requires all collaborators and their permission sets to be specified in the request to modify the file object (via this endpoint).
• contentSize ( For collaborator users, requires the Upload File permission on objectId ) - The size (in bytes) of the file object’s data (in its unencrypted form) to be recorded by the Covata Platform’s Access Service. Specify this value to record the size of a completed file object’s unencrypted data, which is to be encrypted locally by your client application.
  Important:
  • The contentSize value can only be set once on a file object, at which point this property becomes immutable.
  • If you intend to upload the file object’s unencrypted data to storage via the Covata Platform’s Content Service, then omit this parameter. When you make the upload request, the Content Service automatically calculates the size of the unencrypted data and assigns this value to contentSize. The Content Service then proceeds to encrypt the data and send this encrypted data to storage.
  • If you have already specified the contentSize parameter’s value before uploading a file object’s unencrypted data, then the Content Service will be unable to assign the unencrypted data’s size to the contentSize property as it is immutable. The Access and Content Services will record errors in their respective logs. Nevertheless, the unencrypted data will still be encrypted by the Content Service, followed by the encrypted data being sent to storage and associated with the file object.
• labelId ( For collaborator users, requires the Share permission on objectId ) - The ID of the classification to apply to (or modify on) the file object. If this parameter’s value is an empty string or the parameter is omitted altogether, then no classification is applied to the file object and therefore, no classification restrictions (i.e. checks on Covata users’ group membership and the association of these groups with classifications - see User group endpoints for more information) are placed on any collaborators added to this file object.
  Notes:
  • Applying a classification has the potential to restrict access to the file object by any inherited collaborators. Inherited collaborators are collaborators who are able to access this file object because these collaborators were explicitly applied to an ancestral folder.
  • If Covata users’ group memberships (associated with the classification applied to the file object in the request) do not comply with any collaborators applied to this file object (above), then this request will fail.
  • For more information about configuring classifications, see Classification endpoints.
• mimeType ( For collaborator users, requires the Rename permission on objectId ) - The MIME type of the data associated with the file object. For example, if the data to be encrypted into this file object is an image in JPEG format, its MIME type value would be image/jpeg.
• name ( For collaborator users, requires the Rename permission on objectId ) - The name to apply to the file object. For example, any new name for the file and its extension.
• parentId ( For collaborator users, requires the Move permission on objectId ) - The ID of the folder that will contain the file object (i.e. the folder to which the file object will be moved). Specifying a value of 0 results in the file being located at/moved to the default logical root storage location.
  Notes:
  • Omitting this property (or not changing its existing value) results in the file object remaining at its current location.
  • The folder represented by parentId must be within the same organisation as that of the file object.
  • If the Covata user (whose access token is submitted in the header of the request) is a collaborator on both the file object and the folder represented by parentId, then this user must have the Move permission (on both of these items) inherited from a common parent folder, where parentId could also be the common parent folder itself.
  • If the Covata user is a collaborator on the parentId folder but is the owner of the file object (or vice versa), then it is not possible to move the file object into the parentId folder.
• sha512 ( Deprecated. For collaborator users, requires the Upload File permission on objectId and the same collaborator’s user account that initialized this file object ) - The SHA-512 value of the file object’s encrypted data.
  Important:
  • This parameter is deprecated on this endpoint. To set this value on a file object, do so through the <content-service>/api/v1/objects/{objectId}/contents endpoint.
  • The sha512 value can only be set once on a file object, at which point this property becomes immutable.
  • Omitting this parameter when updating an Incomplete file object, leaves this file object in an Incomplete state.
  • Specifying this parameter and its value on an Incomplete file object changes the file object’s state to Created.
  • You can specify this parameter if you have encrypted the file object’s data externally (e.g. locally by your client application) and intend to upload this encrypted data to storage via the Covata Platform’s Content Service.
  • If you have already specified this parameter’s value when you created a new completed file object (whose state is Created), then re-specifying this parameter (with any value) in this PUT request will cause this request to fail.
• shareStartTime ( For collaborator users, requires the Share permission on objectId ) - The date and time from which collaborators can begin accessing the file object’s content. Omitting this member makes the file object’s content available immediately. When specifying this parameter, ensure its value complies with ISO8601 date/time format notation - i.e. “YYYY-MM-DDTHH:MM:SS.SSSZ”.
  Note: This parameter should only be specified in conjunction with the collaborators parameter. If the shareStartTime parameter is specified without the collaborators parameter, then the shareStartTime parameter’s value will not be saved when the request is submitted.
• shareEndTime ( For collaborator users, requires the Share permission on objectId ) - The date and time from which collaborators’ access to the file object’s content ceases. Omitting this member makes the file object’s content available indefinitely (after its shareStartTime). As with shareStartTime, when specifying this parameter, ensure its value complies with ISO8601 date/time format notation - i.e. “YYYY-MM-DDTHH:MM:SS.SSSZ”.
  Note: As for the shareStartTime parameter, the shareEndTime parameter should only be specified in conjunction with the collaborators parameter. Otherwise, the shareEndTime parameter’s value will not be saved when the request is submitted.
  Example (PUT request parameters - modifying a Created file object):
  {
    "collaborators": {
      "list": [
        {
          "email": "chris.collaborator@xy-company.com",
          "permissionSet": {
            "id": 3
          }
        },
        {
          "email": "adhoc.user@another-xy-company.com"
        }
      ]
    },
    "labelId": "0",
    "mimeType": "application/pdf",
    "name": "Executive Report.pdf",
    "shareStartTime": "2016-10-03T05:30:00.000Z",
    "shareEndTime": "2016-10-10T05:30:00.000Z"
  }
  
  Notes:
  • The permission set with an ID of 3 is Modify. See <access-service>/api/v1/permissions/sets for more information about permission sets.
  • If this file object had existing collaborators and permission sets, then these would be overwritten by this example PUT request.

​

Returns

• 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.
  Note: If no shareStartTime was specified or saved above, then this value will be null.
• shareEndTime - The date and time from which collaborators’ access to this file object’s content ceases.
  Note: If no shareEndTime was specified or saved above, then this value will be null.
• shared - A boolean value that indicates whether or not the file object has been shared with any collaborators.
  Note: If the request was made using the access token of an authenticated collaborator user (without the View Other permission) on the file object, then the value returned will be false.
• name - The name of the file object, which was set when the file object was initialized or created, or last updated (via a POST method request to this endpoint). This value is null if the name was never specified.
• sha512 - The unique SHA-512 hash value of the encrypted data associated with the Created/complete file object. For initialized/Incomplete file objects, this value is null.
• owner - A member containing information about the Covata user who is the current owner of the file object. This member contains the following sub-members:
  • email - The email address of the Covata user who owns this file object.
  • firstName - The first name set by this Covata user. This is the first name that appears on the Users page of SafeShare Organisation Administration and the My Account feature of Covata SafeShare for Web.
  • lastName - The last name set by this Covata 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 Covata user on their own account, or enforced for all members of the organisation (by an Organisation administrator).
  • id - The ID of this Covata user’s account.
  • accountType - A member containing the internationalisation (I18N) property key/code ³ for the account type, including the account type’s value (i.e. hard-coded in the Covata 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 Covata Platform. Your client application can exploit this value (instead of i18n above) if I18N is not required.
    ³ Your client application can exploit the Covata Platform’s I18N features, by initially downloading the relevant language bundles (from the the Covata 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 Covata Platform’s I18N features, see Managing internationalisation 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 Covata 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 (true) or not (false) 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.
• 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 (via a POST method request to this endpoint). This value is null if the mimeType was never specified.
• contentSize - The amount of space (in bytes) of the file object’s data (as recorded by the Covata Platform’s Access Service). For initialized/Incomplete file objects, this value should be null.
• 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 Covata 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 Covata 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 (via the POST method on the <access-service>/api/v1/organisations/{orgGroupId}/objects endpoint), 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 (e.g. via a PUT method request to this endpoint), 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.
• 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 Covata 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.
• 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.
• 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 (via a POST method request to this endpoint).
• collaborators - An array containing information about each Covata user who is currently a collaborator on this file object. Each element of this array contains information about one of these Covata 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 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 Covata 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 Covata user account.
  Note: Only an empty array is returned from Covata user accounts who are collaborators on this file object and do not have the View Other permission on it.
  Example (response from a GET request - using the access token of an authenticated owner of the file object):
  {
      "id": "734242448553197568",
      "shareStartTime": "2016-10-03T05:30:00.000Z",
      "shareEndTime": "2016-10-10T05:30:00.000Z",
      "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": [{
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.file.delete",
          "id": "66"
      }, {
          "scopes": ["collection"],
          "nameI18nCode": "server.permission.name.folder.delete",
          "id": "67"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.download",
          "id": "62"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.move",
          "id": "69"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.view",
          "id": "60"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.delete.other",
          "id": "72"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.copy",
          "id": "63"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.print",
          "id": "61"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.share",
          "id": "73"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.rename",
          "id": "68"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.view.other",
          "id": "71"
      }, {
          "scopes": ["collection"],
          "nameI18nCode": "server.permission.name.folder.create",
          "id": "65"
      }, {
          "scopes": ["collection"],
          "nameI18nCode": "server.permission.name.file.upload",
          "id": "64"
      }],
      "mimeType": null,
      "contentSize": "3596924",
      "parentId": "0",
      "originator": {
          "email": "alex.originator@xy-company.com",
          "id": "732856217122553856"
      },
      "state": "server.object.states.created",
      "modifiedAt": "2016-07-26T01:40:58.287Z",
      "createdAt": "2016-07-19T02:57:21.300Z",
      "labelName": null,
      "type": "object",
      "labelId": null,
      "collaborators": [{
          "shareParentId": null,
          "shareName": null,
          "permissionSet": {
              "id": "2",
              "permissions": [{
                  "scopes": ["object", "collection"],
                  "nameI18nCode": "server.permission.name.print",
                  "id": "61"
              }, {
                  "scopes": ["object", "collection"],
                  "nameI18nCode": "server.permission.name.download",
                  "id": "62"
              }, {
                  "scopes": ["object", "collection"],
                  "nameI18nCode": "server.permission.name.view",
                  "id": "60"
              }],
              "scopes": ["object", "collection"],
              "nameI18nCode": "server.permissionset.name.download"
          },
          "email": "adhoc.user@xy-company.com",
          "firstName": null,
          "lastName": null,
          "id": "736759315364757504"
      }, {
          "shareParentId": null,
          "shareName": null,
          "permissionSet": {
              "id": "3",
              "permissions": [{
                  "scopes": ["object", "collection"],
                  "nameI18nCode": "server.permission.name.file.delete",
                  "id": "66"
              }, {
                  "scopes": ["object", "collection"],
                  "nameI18nCode": "server.permission.name.print",
                  "id": "61"
              }, {
                  "scopes": ["collection"],
                  "nameI18nCode": "server.permission.name.folder.delete",
                  "id": "67"
              }, {
                  "scopes": ["object", "collection"],
                  "nameI18nCode": "server.permission.name.download",
                  "id": "62"
              }, {
                  "scopes": ["object", "collection"],
                  "nameI18nCode": "server.permission.name.view",
                  "id": "60"
              }, {
                  "scopes": ["object", "collection"],
                  "nameI18nCode": "server.permission.name.move",
                  "id": "69"
              }, {
                  "scopes": ["object", "collection"],
                  "nameI18nCode": "server.permission.name.rename",
                  "id": "68"
              }, {
                  "scopes": ["object", "collection"],
                  "nameI18nCode": "server.permission.name.view.other",
                  "id": "71"
              }, {
                  "scopes": ["collection"],
                  "nameI18nCode": "server.permission.name.folder.create",
                  "id": "65"
              }, {
                  "scopes": ["collection"],
                  "nameI18nCode": "server.permission.name.file.upload",
                  "id": "64"
              }],
              "scopes": ["object", "collection"],
              "nameI18nCode": "server.permissionset.name.modify"
          },
          "email": "chris.collaborator@xy-company.com",
          "firstName": "Chris",
          "lastName": "Collaborator",
          "id": "732856277868658688"
      }]
  }
  
  Example (response from a GET request - using the access token of an authenticated collaborator on the file object, where this collaborator does not have the ‘View Other’ permission on this file):
  {
      "id": "734242448553197568",
      "shareStartTime": "2016-07-21T01:15:00.000Z",
      "shareEndTime": null,
      "shared": false,
      "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": [{
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.print",
          "id": "61"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.download",
          "id": "62"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.view",
          "id": "60"
      }],
      "mimeType": null,
      "contentSize": "3596924",
      "parentId": "0",
      "originator": {
          "email": "alex.originator@xy-company.com",
          "id": "732856217122553856"
      },
      "state": "server.object.states.created",
      "modifiedAt": "2016-07-26T01:27:10.291Z",
      "createdAt": "2016-07-19T02:57:21.300Z",
      "labelName": null,
      "type": "object",
      "labelId": null,
      "collaborators": []
  }
  
  Example (response from a PUT request - modifying a file object):
  {
      "id": "736488108589498368",
      "shareStartTime": null,
      "shareEndTime": null,
      "shared": true,
      "name": "paraglider.jpg",
      "sha512": null,
      "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": null,
      "extension": "jpg",
      "organisation": {
          "name": "XY Company",
          "description": "",
          "mfaEnabled": false,
          "id": "732855142835470336"
      },
      "permissions": [{
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.file.delete",
          "id": "66"
      }, {
          "scopes": ["collection"],
          "nameI18nCode": "server.permission.name.folder.delete",
          "id": "67"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.download",
          "id": "62"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.move",
          "id": "69"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.view",
          "id": "60"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.delete.other",
          "id": "72"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.copy",
          "id": "63"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.print",
          "id": "61"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.share",
          "id": "73"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.rename",
          "id": "68"
      }, {
          "scopes": ["object", "collection"],
          "nameI18nCode": "server.permission.name.view.other",
          "id": "71"
      }, {
          "scopes": ["collection"],
          "nameI18nCode": "server.permission.name.folder.create",
          "id": "65"
      }, {
          "scopes": ["collection"],
          "nameI18nCode": "server.permission.name.file.upload",
          "id": "64"
      }],
      "mimeType": "image/jpeg",
      "contentSize": null,
      "parentId": "736437666564194304",
      "originator": {
          "email": "chris.collaborator@xy-company.com",
          "id": "732856277868658688"
      },
      "state": "server.object.states.incomplete",
      "modifiedAt": "2016-07-26T03:54:15.156Z",
      "createdAt": "2016-07-25T07:40:48.375Z",
      "labelName": null,
      "type": "object",
      "labelId": null,
      "collaborators": [{
          "shareParentId": null,
          "shareName": null,
          "permissionSet": {
              "id": "2",
              "permissions": [{
                  "scopes": ["object", "collection"],
                  "nameI18nCode": "server.permission.name.print",
                  "id": "61"
              }, {
                  "scopes": ["object", "collection"],
                  "nameI18nCode": "server.permission.name.download",
                  "id": "62"
              }, {
                  "scopes": ["object", "collection"],
                  "nameI18nCode": "server.permission.name.view",
                  "id": "60"
              }],
              "scopes": ["object", "collection"],
              "nameI18nCode": "server.permissionset.name.download"
          },
          "email": "chris.collaborator@xy-company.com",
          "firstName": "Chris",
          "lastName": "Collaborator",
          "id": "732856277868658688"
      }]
  }