> ## 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/userwhitelist

## URL structure&#x20;

```text theme={null}
https://access-service.xy-company.com/api/v1/userwhitelist
```

## Supported methods and overview&#x20;

* `POST` - used to add one or more new [user whitelist rule(s)](/3.1/admin/managing-user-whitelists.md).
* `GET` - used to retrieve a list of field information for all existing user whitelist rules on the Covata Platform.

## Detailed description&#x20;

This API endpoint servers a number of purposes:

* Adds one or more new user whitelist rule(s) to the Covata Platform. \

  **Note:** The user whitelist feature becomes enabled when at least one rule has been added to/is specified on the Covata Platform. When the user whitelist feature is enabled, be aware that:

  * Adding one or more new user whitelist rule(s) may disable several [Covata user](/3.1/admin/administering-users.md) accounts. Hence, before doing this, it is advisable to first check which Covata user accounts will be disabled by calling the [\<access-service>/api/v1/userwhitelist/check](/3.1/api/access-service-api-v1-userwhitelist-check.md) 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**.
  * Covata Platform administrator accounts cannot be disabled through a user whitelist rule. Therefore, there is no need to add any user whitelist rules to prevent Covata Platform administrators from being disabled. Covata user accounts with the [System administrator role](/3.1/admin/administering-users.md#system-administrator-role) can only be disabled through the [\<access-service>/api/v1/users/\{userId}/enable](/3.1/api/access-service-api-v1-users-userid-enable.md) or [\<access-service>/api/v1/users/bulk](/3.1/api/access-service-api-v1-users-bulk.md) API endpoints.
  * If a disabled Covata user account is [(re-)enabled](/3.1/api/access-service-api-v1-users-userid-enable.md) and its email address does not match that of an existing user whitelist rule, then that account's email address is automatically added as a new whitelist rule upon (re-)enabling the account.
  * Any [LDAP](/3.1/admin/administering-users.md#account-type) user accounts that were originally disabled by not matching/complying with an existing user whitelist rule (but now comply with a newly added rule) are automatically re-enabled when the Covata Platform next synchronizes with the LDAP server.
* Retrieves a list of field information for all existing user whitelist rules on the Covata Platform. The list of user whitelist rules returned in the [response](/3.1/api/access-service-api-v1-userwhitelist.md#access-service-api-v1-userwhitelist-returns-from-a-GET-request) can be ordered, sorted and paginated.

## Supported roles&#x20;

This API endpoint supports the following Covata user [roles](/3.1/admin/administering-users.md#a-users-roles) (as described in the [Covata Platform Administrator's Guide](/3.1/admin.md)):

* [System administrator](/3.1/admin/administering-users.md#system-administrator-role)

The Covata Platform's resources available to one of these Covata users (above) is determined by the access token passed in the [header](/3.1/api/access-service-api-v1-userwhitelist.md#access-service-api-v1-userwhitelist-required-headers) of requests to this endpoint.

## Required headers&#x20;

The appropriate access token as the `Bearer` token:

* `Authorization: Bearer a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6`

The following header is required if the body of the request has a JSON object:

* `Content-Type: application/json`

## Required parameters on POST&#x20;

The following required parameters must be sent in the body of the POST request, each as individual members of a JSON object:

* **items** - .

  * **pattern** - .
  * **description** - .

  **Example ():**

## Optional parameters on GET&#x20;

The following optional parameters can be sent in the URL of the GET request:

* **limit** - .
* **offset** - .
* **orderBy** - .
* **sortBy** - .

  **Example ():**

## Returns from a POST request&#x20;

A JSON-formmatted response consisting of an array containing information about each user whitelist rule (added to the user whitelist), where each element of the array contains the members: `id`, `pattern` and `description`. See [Returns from a GET request](/3.1/api/access-service-api-v1-userwhitelist.md#access-service-api-v1-userwhitelist-returns-from-a-GET-request) for details about these members.

## Returns from a GET request&#x20;

A JSON-formatted response containing the following members:

* **items** - An array containing information about each user whitelist rule.

  * **id** - .
  * **pattern** - .
  * **description** - .
* **count** - .
* **offset** - .

  **Example (response from ...):**


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