<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 organisation and {whitelistId} is the ID of a user whitelist rule.

Supported methods and overview

• PUT - modifies the description of an existing user whitelist rule (specified by whitelistId) in an organisation (specified by orgId).
• DELETE - deletes an existing user whitelist rule (specified by whitelistId) from an organisation (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 organisation (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 organisation (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 organisation (specified by orgId).
  Note: Deleting the last user whitelist rule in an organisation results in the user whitelist feature being disabled for that organisation. It is possible to first check which Cocoon Data 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 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 {orgId} 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 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"
  }