URL structure

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

where {orgGroupId} is the ID of an organisation.

Supported methods and overview

POST - adds a Cocoon Data user account ¹ to an organisation (specified by orgGroupId).
GET - retrieves a list of information associated with existing users within an organisation (specified by orgGroupId).

Detailed description

This API endpoint serves a number of purposes:

Adds a Cocoon Data user account ¹ to an organisation (specified by orgGroupId).
Note: Any valid (combination of) role(s) can be assigned to this user account. The exception to this are Cocoon Data user accounts with the Ad hoc role (which are automatically created and added to an organisation when a user with the Originator role (in this organisation) shares their content with someone whose email address has not yet been registered (i.e. is part of an existing account) on the Cocoon Data Platform.
Retrieves a list of information associated with existing users in an organisation (specified by orgGroupId). The list of users returned in the response can be filtered according to users whose email address, first name or last name contains the string specified in the request.

¹ If a Cocoon Data user account is not already registered on the Cocoon Data Platform, then making this request automatically creates this user account.

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 one of these Cocoon Data users (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:

email - The email address of the Cocoon Data user account to add to the organisation specified by {orgGroupId} in the request's URL.
roles - An array of elements, each of which is an enumeration (enum) value representing a role to assign to this user when their account is added to the organisation specified by {orgGroupId} in the URL. Valid values and combinations of these roles include:
- ROLE_ORIGINATOR - Applies the Originator role to this user account in this organisation.
  Note: To apply this role, at least one plan must be configured in this organisation - see the <access-service>/api/v1/organisations/{orgGroupId}/plans API endpoint for more information.
- ROLE_COLLABORATOR - Applies the Collaborator role to this user account in this organisation.
  Note: This role cannot be specified in the same request with ROLE_ORIGINATOR (above).
- ROLE_ORGANISATION_ADMIN - Applies the Organisation administrator role to this user account in this organisation.
  Note: This role can be applied in conjunction with ROLE_ORIGINATOR and ROLE_COLLABORATOR (above).
planId ( only required if the roles array above contains ROLE_ORIGINATOR ) - The ID of the plan to assign to this user.
Example (POST request - adding a user with the 'Originator' role to the organisation specified by {orgGroupId} in the URL):
{

"email": "alex.originator@xy-company.com",

"roles": [ "ROLE_ORIGINATOR" ],

"planId": "749419742544326656"

}

Example (POST request - adding a user with both the 'Organisation administrator' and 'Originator' roles to the organisation specified by {orgGroupId} in the URL):
{

"email": "alex.originator@xy-company.com",

"roles": [ "ROLE_ORIGINATOR", "ROLE_ORGANISATION_ADMIN" ],

"planId": "749419742544326656"

}

Optional GET-request parameters

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

searchText - Any text substring used to filter for all Cocoon Data users who are currently members of the organisation specified by {orgGroupId} in the request's URL, where this text substring must match that of the user account's field specified in searchColumn below (or any of these fields). If this parameter is omitted, then no filtering is performed.
searchColumn - The user's field upon which the text substring (specified in searchText above) is used for filtering user accounts returned in the response. The fields available to this text searching include:
- email - the email address associated with the Cocoon Data user.
- firstName - the first name (set by this user),
- lastName - the last name (set by this user),
- all - any of these fields above.
If this parameter is omitted, then no filtering is performed.
limit - An integer value from 0 to 100, representing the maximum number of items to be returned in the response from the Cocoon Data Platform, where an individual item is information about a Cocoon Data user in the organisation (specified by {orgGroupId} in the URL). If this parameter is omitted, then its value is 10 by default.
offset - A value representing the count order of all retrievable items (i.e. Cocoon Data users in the organisation specified by {orgGroupId} in the URL) from the Cocoon Data Platform returned in the response. Calls to this API endpoint may amount to potentially unmanageable numbers of items being returned. Since the order of these items in the response could differ significantly, based on the values of the orderBy and sortBy parameters below, this offset parameter provides pagination for items returned in responses, allowing items to be retrieved from any count greater than 0 (i.e. the first item returned in a response). If this parameter is omitted, then its value is 0 by default.
orderBy - An enumeration (enum) value representing the order in which items (i.e. Cocoon Data users with the SafeShare administrator role) are returned in the response. This parameter orders items according to the value of the sortBy parameter specified below. Ordering items can be in either ascending alphanumeric order (by specifying the value ASC for this parameter) or descending order (by specifying the value DESC). If this parameter is omitted, then its value is ASC by default.
sortBy - A value representing the field (i.e. member) of a retrieved item by which items (i.e. Cocoon Data users with the SafeShare administrator role) returned in the response will be sorted. Valid field values for this parameter include:
- email - the email address associated with the Cocoon Data user,
- firstName - the first name (set by this user),
- lastName - the last name (set by this user) and
- userId - the ID of the Cocoon Data user account.
If this parameter is omitted, then its value is email by default.
Example (GET request):
1 https://access-service.xy-company.com/api/v1/users?searchText=originator&searchColumn=email

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 ) - An array containing information about all Cocoon Data user accounts in the organisation specified by {orgGroupId} in the request's URL, which have been filtered by any parameters submitted in the request. Each element of this array contains information about one of these user accounts (represented as an object containing the following members unless otherwise stated).
email - The email address of the Cocoon Data user account which as been added to or retrieved from the organisation specified by {orgGroupId} in the URL.
firstName - The first name set by this user, which is null for newly added Cocoon Data user accounts that were not already registered on the Cocoon Data Platform. 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, which is null for newly added Cocoon Data user accounts that were not already registered on the Cocoon Data Platform. 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 is null for newly added Cocoon Data user accounts that were not already registered on the Cocoon Data Platform. This name appears on the My Account feature of SafeShare for Web.
mobileNumber - The mobile number set by this user, which is null for newly added Cocoon Data user accounts that were not already registered on the Cocoon Data Platform. This number 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 added to 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.
count ( from GET requests only ) - The total number of items (i.e. Cocoon Data users in the organisation specified by {orgGroupId} in the URL) that can be returned in the response.
Note: If the searchText and searchColumn parameters were specified in the request, then this value represents the number of items (above) returned in the response.
offset ( from GET requests only ) - The value of the offset which had been used in the request to this API endpoint.
Example (response from a POST request):
{

"email": "alex.originator@xy-company.com",

"firstName": "Alex",

"lastName": "Originator",

"otherName": null,

"mobileNumber": null,

"mfaEnabled": false,

"enabled": true,

"accountNonLocked": true,

"numFailedLogins": 0,

"organisations": [{

"id": "749418071827214336",

"name": "XY Company",

"addressBookEnabled": false,

"watermarkingEnabled": false,

"plan": {

"id": "749419742544326656",

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

}],

"mfaEnabled": false,

"bytesUploaded": "0",

"bytesRecycled": null

}],

"id": "749419842687528960",

"accountType": {

"i18n": {

"code": "server.useraccounttype.local",

"arguments": []

},

"value": "LOCAL"

}

}