<access-service>/api/v1/organisations/{orgId}/userwhitelist

​

URL structure

https://access-service.xy-company.com/api/v1/organisations/{orgId}/userwhitelist

​

Supported methods and overview

• POST - adds one or more new user whitelist rule/s to an organization (specified by orgId).
• GET - retrieves a list of information for all existing user whitelist rules configured in an organization (specified by orgId).

​

Detailed description

• Adds one or more new user whitelist rule/s to an organization (specified by orgId). If the email addresses of any Covata users do not match/comply with any user whitelist rule configured in the organization, then these users cannot be shared items by other users within the organization. This also includes anyone else who does not yet have a user account registered on the Covata Platform but whose email address does not match/comply with an existing user whitelist rule.
  Note: The user whitelist feature becomes enabled when at least one rule has been added to/is specified in the organization. It possible to first check which existing Covata user accounts will be affected (i.e. prevented from being shared content) within the organization by calling the <access-service>/api/v1/organisations/{orgId}/userwhitelist/check API endpoint with an action parameter value of add in the JSON object, along with each pattern (i.e. an individual rule to be added) as an array of items.
• Retrieves a list of information for all existing user whitelist rules configured in an organization (specified by orgId). The list of user whitelist rules returned in the response can be ordered, sorted and paginated.

​

Supported roles and conditions

• Organization administrator - when this user is a member of the organization specified by {orgId} in the request’s URL.

​

Required headers

• Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

• Content-Type: application/json

​

Required POST-request parameters

• items - .
  • pattern - The domain or email address of the user whitelist rule to add to the organization specified by {orgId} in the request’s URL.
  • description - The description for this new user whitelist rule.
  Example (request):
  {
    "items": [
      {
        "pattern": "xy-company.com",
        "description": "XY Company staff"
      }
    ]
  }
  

​

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 a user whitelist entry in the organization (specified by {orgId} in the request’s URL). 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. user whitelist entries in the organization specified by {orgId} in the URL) 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. user whitelist entries in the organization specified by {orgId} in the URL) 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. user whitelist entries in the organization specified by {orgId} in the URL) returned in the response will be sorted. Valid field values for this parameter include:
  • pattern - the domain or email address of the user whitelist rule,
  • description - the description of the user whitelist rule,
  • created - the date and time when the user whitelist rule was created and
  • modified - the date and time when the user whitelist rule was last modified.
  Example (request):
  https://access-service.xy-company.com/api/v1/organisations/760756644367081472/userwhitelist?offset=1&orderBy=DESC&sortBy=created
  

​

Returns

• items ( from GET requests only ) - An array containing information about all existing user whitelist rules configured in the organization (specified by {orgId} in the request’s URL), where these rules have been filtered by any parameters submitted in the request. Each element of this array contains information about one of these user whitelist rules (represented as an object containing the following members unless otherwise stated).
  • id - The ID of the user whitelist rule.
  • pattern - The domain or email address of this user whitelist rule.
  • description - The description of this user whitelist rule.
• count ( from GET requests only ) - The maximum number of items (i.e. user whitelist entries in the organization specified by {orgId} in the URL) that can be returned in the response.
• offset ( from GET requests only ) - The value of the offset which had been used in the request to this endpoint.
  Example (response from a GET request):
  {
      "items": [{
          "id": "765456269464346624",
          "pattern": "xy-company.com",
          "description": "XY Company staff"
      }, {
          "id": "765708906118029312",
          "pattern": "*.xy-company.com",
          "description": "Other XY Company staff"
      }],
      "count": "2",
      "offset": "0"
  }