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

URL structure

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

where {orgId} is the ID of an organization and {whitelistId} is the ID of a user whitelist rule.

Supported methods and overview

• PUT - used to modify the description of an existing user whitelist rule (specified by whitelistId) in an organization (specified by orgId).
• DELETE - used to delete an existing user whitelist rule (specified by whitelistId) from an organization (specified by orgId).

Note: The DELETE method takes no parameters.

Detailed description

This API endpoint serves a number of purposes:

• Modifies the description of an existing user whitelist rule (specified by whitelistId) in an organization (specified by orgId). A user whitelist rule's ID can be obtained by calling the GET method of the <access-service>/api/v1/organisations/{orgId}/userwhitelist API endpoint, which retrieves a list of information for all user whitelist rules in an organization (specified by orgId).
  Note: It is not possible to modify a user whitelist rule's domain pattern or email address (i.e. the rule itself) as this is equivalent to deleting the rule (via this API endpoint) and adding a new one (via the <access-service>/api/v1/organisations/{orgId}/userwhitelist endpoint).
• Deletes an existing user whitelist rule (specified by whitelistId) from an organization (specified by orgId).
  Note: Deleting the last user whitelist rule in an organization results in the user whitelist feature being disabled for that organization. It is possible to first check which Covata user accounts will be be affected (i.e. regain the ability to be shared content) by calling the <access-service>/api/v1/organisations/{orgId}/userwhitelist/check API endpoint with an action parameter value of delete in the JSON object, along with a single id (i.e. of the whitelist rule to be deleted) in the items array.

Supported roles and conditions

This API endpoint supports requests utilizing Covata user accounts with the following roles (as described in the Organization Administrator's Guide) and conditions:

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

The Covata Platform's resources available to a Covata 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 parameters

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

• pattern - The domain pattern or email address of the user whitelist rule whose description is to be modified.
• description - The updated description for this user whitelist rule.
  Example (request):

  {  
    "pattern": "*.xy-company.com",
    "description": "Other XY Company staff accounts"
  }

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:

• id - The ID of the user whitelist rule.
• pattern - The domain or email address of this user whitelist rule.
• description - The (updated) description of this user whitelist rule.
  Example (response):

  {
      "id": "765708906118029312",
      "pattern": "*.xy-company.com",
      "description": "Other XY Company staff accounts"
  }