<access-service>/api/v1/organisations/{orgGroupId}/users/{userId}

URL structure

https://access-service.xy-company.com/api/v1/organisations/{orgGroupId}/users/{userId}

where {orgGroupId} is the ID of an organisation and {userId} is the ID of a Cocoon Data user account.

Supported methods and overview

• PUT - modifies the role-related fields of a Cocoon Data user account (specified by userId) in an organisation (specified by orgGroupId).
• DELETE - removes a Cocoon Data user account (specified by userId) from an organisation (specified by orgGroupId).

Note: The DELETE method takes no parameters.

Detailed description

This API endpoint serves a number of purposes:

• Modifies the role-related fields of an existing Cocoon Data user account (specified by userId) in an organisation (specified by orgGroupId). These fields include the user's Role, Is Organisation Admin? flag and current Plan. For more information about these fields, see An organisation user's fields in the Organisation Administrator's Guide.
  Note: A Cocoon Data user account's ID can be obtained by calling the GET method of the <access-service>/api/v1/organisations/{orgGroupId}/users API endpoint, which retrieves a list of information associated with existing users in an organisation (specified by orgGroupId), which can be filtered through a variety of 'search' criteria.
• Removes a Cocoon Data user account (specified by userId) from an organisation (specified by orgGroupId). Be aware that this action permanently deletes this user's file objects and folders from the Cocoon Data Platform (such that any data or information about these items can no longer be retrieved) through the Cocoon Data API. However, all reporting data associated with these items is still retained and can be accessed through the organisation's auditing and reporting endpoints.
  Tip: You can remove a Cocoon Data user from an organisation and retain this user's file objects and folders by transferring the ownership of these items from this user to that of another. For more information, see <access-service>/api/v1/organisations/{orgId}/items/transfer.

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:

• Organisation administrator - when this user is a member of the organisation specified by {orgGroupId} in the request's URL.

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 PUT-request parameters

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

• roles - An array of elements, each of which is an enumeration (enum) value representing a role to assign to this user (specified by {userId} in the URL) within the organisation (specified by {orgGroupId}) when their account is being modified. Valid values and combinations of these roles include:
  • ROLE_ORIGINATOR - Applies the Originator role to an existing user account which has either the Collaborator or Ad hoc roles in this organisation. Also retains the Originator role for an existing user with this role (when a PUT-requests are made to this endpoint).
  • ROLE_COLLABORATOR - Applies the Collaborator role to an existing user account which has the Ad hoc role in this organisation. Also retains the Collaborator role for an existing user with this role (when a PUT-requests are made to this endpoint).
    Notes:
    • This action sets a temporary password (generated by the Cocoon Data Platform) on a user's account with the Ad hoc role.
    • It is not possible to downgrade an existing user account's role from Originator to Collaborator by applying the ROLE_COLLABORATOR value to an account which had ROLE_ORIGINATOR previously applied to it in this organisation.
    • The ROLE_ORIGINATOR and ROLE_COLLABORATOR values cannot be applied in the same request.
  • ROLE_ORGANISATION_ADMIN - applies the Organisation administrator role to this user in this organisation, or removes it by omitting this value. Also retains the Organisation administrator role for an existing user with this role (when a PUT-requests are made to this endpoint).
    Notes:
    • The ROLE_ORGANISATION_ADMIN value must be used in conjunction with a ROLE_ORIGINATOR or ROLE_COLLABORATOR value (above). If you are only applying the Organisation administrator role to an existing user in the organisation (and not changing this user's current role from Collaborator to Originator or Ad hoc to Collaborator), then re-apply the same value in the request - i.e. ROLE_ORIGINATOR or ROLE_COLLABORATOR - that had previously been applied to this user. For example, specify the array [ "ROLE_ORIGINATOR", "ROLE_ORGANISATION_ADMIN" ] to apply the Organisation administrator role to a user who already has the Originator role.
    • To remove the Organisation administrator role from a user account, omit the value ROLE_ORGANISATION_ADMIN in the request and only use the relevant value ROLE_ORIGINATOR or ROLE_COLLABORATOR in the array.
• planId ( only required if the roles array above contains ROLE_ORIGINATOR ) - The ID of the plan to assign (or which has already been assigned) to this user.
  Example (PUT request - applying both the 'Organisation administrator' and 'Originator' role to an existing user in the organisation specified by {orgGroupId} in the URL, where this user has either the 'Collaborator' or 'Ad hoc' roles):

  {
      "roles": [ "ROLE_ORIGINATOR", "ROLE_ORGANISATION_ADMIN" ],
      "planId": "749419742544326656"
  }

  Note: This could also be a request to apply just the Organisation administrator role to an existing user in the organisation, where this user already has the Originator role.
  Example (PUT request - applying the 'Collaborator' role to an existing user in the organisation specified by {orgGroupId} in the URL, where this user has the 'Ad hoc' role):

  {
      "roles": [ "ROLE_COLLABORATOR" ]
  }

  Note: This could also be a request to remove the Organisation administrator role from an existing user in the organisation, where this user already has the Collaborator role.

Returns

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

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

• email - The email address of the modified Cocoon Data user account in the organisation specified by {orgGroupId} in the URL.
• firstName - The first name set by this user. This is the first name that appears on the Users page of SafeShare Organisation Administration and/or the My Account feature of Cocoon Data SafeShare for Web.
• lastName - The last name set by this user. Like the first name (above), this appears on the User page of Organisation Administration and/or the My Account feature of SafeShare for Web.
• otherName - The other name (e.g. middle) set by this user, which appears on the My Account feature of SafeShare for Web.
• mobileNumber - The mobile number set by this user, which appears on the My Account feature of SafeShare for Web.
• mfaEnabled - A boolean value that indicates whether (true) or not (false) two-factor authentication has either been set by this user on their own account, or enforced for all members of the organisation (by any Organisation administrator of this organisation).
• enabled - A boolean value that indicates whether (true) or not (false) this user's account has any role, such as a role assigned above when this account was modified in this organisation (specified by {orgGroupId} in the URL). This value should be true.
• accountNonLocked - A boolean value that indicates whether (false) or not (true) this user's account is locked. A Cocoon Data user account may become locked as a result of the user mistyping their password more than the maximum number of times configured (by themselves or another SafeShare administrator of their Cocoon Data Platform instance). The user themselves will need to unlock this account by following the instructions in their 'account lockout' notification (or by resetting their password via any of the options on the Cocoon Data Sign-in page).
• numFailedLogins - The number of times this user failed to successfully sign in.
• organisations - An array containing information about the organisation specified by {orgGroupId} in the URL. This single element array contains information about this organisation (represented as an object containing the following members unless otherwise stated).
  • id - The ID of this organisation.
  • name - The name of this organisation, which is configurable by a SafeShare administrator.
  • addressBookEnabled - A boolean value that indicates whether (true) or not (false) this organisation's address book feature has been enabled.
  • watermarkingEnabled - A boolean value that indicates whether (true) or not (false) the watermarking feature is enabled for all viewable files created within this organisation.
  • plan - A member containing information about the plan defined in this organisation which has been assigned to this user. This member contains the following sub-members:
    • id - The ID of this plan.
    • name - The name of this plan.
    • description - The description of this plan.
    • quota - This plan's current quota (in mebibytes/MiB).
    • default - A boolean value that indicates whether (true) or not (false) this plan is currently set as the default plan.
    Note: This member's value is null if no plan is associated with this user.
  • adminEmail - The contact email address for this organisation, typically for an Organisation administrator, which is:
    • used in email notifications and
    • is accessible from the Need help? ... link on the Authentication code entry page for two-factor authentication (2FA).
    A value of null indicates that a value has not yet been set for this property (and that the equivalent property defined in SafeShare Administration is being used).
  • organisationAlias - .
  • userMessage - The custom message (typically a warning) defined for this organisation, which will be shown at the base of the 'Share' dialog box. A value of null indicates that a value has not yet been defined for this property (and that the equivalent property defined in SafeShare Administration is being used).
  • supportUrl - The URL of the company's/organisation's support page for this organisation, which is accessible from the Support link in the footer of SafeShare web application pages. A value of null indicates that a value has not yet been set for this property (and that the equivalent property defined in SafeShare Administration is being used).
  • companyName - The name of the company/organisation for this organisation, which appears throughout email notifications. A value of null indicates that a value has not yet been set for this property (and that the equivalent property defined in SafeShare Administration is being used).
  • legalUrl - The URL of the company's/organisation's legal page, which is accessible from the Legal link in the footer of SafeShare web application pages. A value of null indicates that a value has not yet been set for this property (and that the equivalent property defined in SafeShare Administration is being used).
  • webappHelpUrl - The URL of the help documentation for the Cocoon Data SafeShare for Web application. A value of null indicates that a value has not yet been set for this property (and that the equivalent property defined in SafeShare Administration is being used).
  • orgAdminHelpUrl - The URL of the help documentation for SafeShare Organisation Administration. A value of null indicates that a value has not yet been set for this property (and that the equivalent property defined in SafeShare Administration is being used).
  • privacyUrl - The custom URL of the company's/organisation's privacy statement page for this organisation, which is accessible from the Privacy:
    • link in the footer of SafeShare web application pages,
    • options in the taskbar notification area pop-up menu and application page of SafeShare for Windows and
    • link in the sign-in dialog box and Help > Privacy option from the SafeShare menu bar of SafeShare for OS X.
    A value of null indicates that a value has not yet been set for this property (and that the equivalent property defined in SafeShare Administration is being used).
  • securityRoles - An array containing information about the internationalization (I18N) property key/code ^* for each role assigned to the user above in this organisation. Each element of this array contains information about one of these roles, including each role's value (i.e. hard-coded in the Cocoon Data Platform), represented as an object containing the following members:
    • i18n - A member containing the I18N code ^* for the role as sub-members:
      • code - The I18N code for the role's value. This I18N code could include the substring originator, collaborator, organisationadmin, systemadmin (for SafeShare administrator role) or adhoccollaborator (for the Ad hoc role).
      • arguments - An array containing any arguments/variables that constitute the value of the I18N code above. Since none of the roles' values contain any variables, this array is always empty.
    • value - The value of securityRoles 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.
  • mfaEnabled - A boolean value that indicates whether (true) or not (false) two-factor authentication has been enforced for all members of this organisation.
  • bytesUploaded - The total number of bytes of data that this user has uploaded through this organisation.
  • bytesRecycled - The total number of bytes of data that this user has in their Recycle Bin for this organisation.
• id - The ID of this Cocoon Data user 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.
  Example (response from a PUT request):

  {
      "email": "chris.collaborator@xy-company.com",
      "firstName": "Chris",
      "lastName": "Collaborator",
      "otherName": null,
      "mobileNumber": null,
      "mfaEnabled": false,
      "enabled": true,
      "accountNonLocked": true,
      "numFailedLogins": 0,
      "organisations": [{
          "id": "759955653086449664",
          "name": "XY Company",
          "addressBookEnabled": false,
          "watermarkingEnabled": false,
          "plan": {
              "id": "759956495290109952",
              "name": "Staff Originators",
              "description": "Staff members with the Originator role.",
              "quota": 10240,
              "default": true
          },
          "adminEmail": null,
          "organisationAlias": null,
          "userMessage": null,
          "supportUrl": null,
          "companyName": null,
          "legalUrl": null,
          "webappHelpUrl": null,
          "orgAdminHelpUrl": null,
          "privacyUrl": null,
          "securityRoles": [{
              "i18n": {
                  "code": "db.securityroles.originator",
                  "arguments": []
              },
              "value": "ROLE_ORIGINATOR"
          }, {
              "i18n": {
                  "code": "db.securityroles.organisationadmin",
                  "arguments": []
              },
              "value": "ROLE_ORGANISATION_ADMIN"
          }],
          "mfaEnabled": false,
          "bytesUploaded": "0",
          "bytesRecycled": null
      }],
      "id": "759958258042834944",
      "accountType": {
          "i18n": {
              "code": "server.useraccounttype.local",
              "arguments": []
          },
          "value": "LOCAL"
      }
  }