> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cocoondata.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

## URL structure&#x20;

```text theme={null}
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&#x20;

* `PUT` - used to modify the description of an existing [user whitelist rule](/3.3/admin-org/managing-user-whitelists.md) (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&#x20;

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](/3.3/api/access-service-api-v1-organisations-orgid-userwhitelist.md) 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](/3.3/api/access-service-api-v1-organisations-orgid-userwhitelist.md) 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](/3.3/api/access-service-api-v1-organisations-orgid-userwhitelist-check.md) 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&#x20;

This API endpoint supports requests utilizing Covata user accounts with the following [roles](/3.3/admin-org/administering-users-within-an-organisation.md#an-organisation-users-roles) (as described in the [Organization Administrator's Guide](/3.3/admin-org.md)) and conditions:

* [Organization administrator](/3.3/admin-org/administering-users-within-an-organisation.md#organisation-administrator-role) - 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](/3.3/api/access-service-api-v1-organisations-orgid-userwhitelist-whitelistid.md#access-service-api-v1-organisations-orgid-userwhitelist-whitelistid-required-headers) of requests to this endpoint.

## Required headers&#x20;

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&#x20;

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):**

  ```json theme={null}
  {
    "pattern": "*.xy-company.com",
    "description": "Other XY Company staff accounts"
  }
  ```

## Returns&#x20;

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):**

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.