<access-service>/api/v1/organisations

​

URL structure

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

​

Supported methods and overview

• POST - adds a new organization to the Covata Platform.
• GET - retrieves information about all organizations configured on the Covata Platform.

​

Detailed description

• Adds a new organization to the Covata Platform.
• Retrieves information about all organizations configured on the Covata Platform.

​

Supported roles and conditions

• Safe Share administrator - using the:
  • POST method, when no LDAP connection has been configured on the Covata Platform. To retrieve information about all configured LDAP connections on the Covata Platform, see <access-service>/api/v1/ldapconnections.
  • GET method, without any futher conditions.

​

Required headers

• Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

• Content-Type: application/json

​

Required POST-request parameters

• name - The initial name for the new organization.
• quota - The initial quota for the organization (in MiB).
  Note: A MiB is a mebibyte, where one MiB = 1 x 1024 x 1024 bytes = 1048576 bytes.
• adminEmail - The email address of the initial Organization administrator of this organization.
• contactEmail - The email address of the initial Contact Person of this organization.
  Notes:
  • This property appears under the name The email address of the organization’s contact person on the Configuration page in Organization Administration.
  • When adding a new organization through Safe Share Administration, both this property and the adminEmail property (above) are set with the same value. However, this API endpoint provides the ability to set these two properties with different email addresses (in a single request to this API).
  Example (request):
  {
    "name": "Another Org.",
    "quota": 2094080,
    "adminEmail": "org.administrator@xy-company.com",
    "contactEmail": "org.administrator@xy-company.com"
  }
  

​

Optional POST-request parameters

• description - The initial description for the new organization.
  Note: This property appears under the name A brief description of the organization on the Configuration page in Organization Administration. However, as described in the Configuring Safe Share Organization Administration properties page of the Organization Administrator’s Guide, this property is currently of limited use.
  Example (request):
  {
    "name": "Another Org.",
    "description": "The brief description for Another Org.",
    "quota": 2094080,
    "adminEmail": "org.administrator@xy-company.com",
    "contactEmail": "org.administrator@xy-company.com"
  }
  

​

Optional GET-request parameters

• limit - An integer value from 0 to 100, representing the maximum number of items to be returned in the response, where an individual item is information about an organization configured on the Covata Platform. If this parameter is omitted, then its value is 0 by default, which does not apply restrictions to the number of items returned in the response.
• offset - A value representing the count order of all retrievable items (i.e. organizations configured on the Covata Platform) returned in the response. Calls to this API endpoint may amount to potentially large numbers of items being returned from the Covata Platform. 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. organizations configured on the Covata Platform) 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. organizations configured on the Covata Platform) returned in the response will be sorted. Valid field values for this parameter include:
  • id - the ID of the organization,
  • name - the name of the organization,
  • contact_email - the email address of the organization’s Contact Person,
  • quota - the name of the organization and
  • description - the description of the organization.
  Example (request):
  https://access-service.xy-company.com/api/v1/organisations?sortBy=name
  

​

Returns

• items - .
• name - .
• description - .
• quota - .
• contactEmail - .
• enabled - .
• adhocSharingDisabled - A boolean value indicating whether (false) or not (true) Covata users in this organization are allowed to share items with people who are not already members of the organization.
• organisationRemovalRequest - A member containing the following sub-members that relate to the organization’s removal request (initiated by a Safe Share administrator). If no removal request has been made on this organization, then this member’s value is null.
  • id - The ID of this organization.
  • initiatorId - The ID of the Safe Share administrator’s user account that initiated this organization’s removal request.
  • notificationEnabled - A boolean value indicating whether (true) or not (false) the organization’s contact person was sent an email notification informing them that a Safe Share administrator had initiated a request to remove their organization from the Covata Platform.
  • daysToAction - Indicates the number of days remaining before before a Safe Share administrator should perform further action on this organization’s removal request.
    Note: If the Days to action organization removal property value (accessible through the <access-service>/api/v1/config/theme/orgRemovalActionDays API endpoint) is cleared, then this sub-member’s value will always return null.
• id - The ID of this organization.
• modifiedAt - .
• createdAt - .
• count - .
• offset - .
  Example (response from a POST request):
  {
      "name": "Another Org.",
      "description": "The brief description for Another Org.",
      "quota": 2094080,
      "contactEmail": "org.administrator@xy-company.com",
      "enabled": true,
      "adhocSharingDisabled": false,
      "organisationRemovalRequest": null,
      "id": "769407354122051584",
      "modifiedAt": "2016-10-24T03:50:08.120Z",
      "createdAt": "2016-10-24T03:50:08.120Z"
  }
  
  
  Example (response from a GET request):
  {
      "items": [{
          "name": "Default",
          "description": "",
          "quota": 0,
          "contactEmail": "",
          "enabled": true,
          "adhocSharingDisabled": false,
          "organisationRemovalRequest": null,
          "id": "1",
          "modifiedAt": "1970-01-01T00:00:00.000Z",
          "createdAt": "1970-01-01T00:00:00.000Z"
      }, {
          "name": "XY Company",
          "description": "",
          "quota": 4194304,
          "contactEmail": "org.administrator@xy-company.com",
          "enabled": true,
          "adhocSharingDisabled": false,
          "organisationRemovalRequest": {
              "id": 760756644367081472,
              "initiatorId": 783117434474610688,
              "notificationEnabled": true,
              "daysToAction": 29
          },
          "id": "760756644367081472",
          "modifiedAt": "2016-10-10T06:34:19.254Z",
          "createdAt": "2016-09-30T06:55:18.192Z"
      }],
      "count": "2",
      "offset": "0"
  }