URL structure
1 https://access-service.xy-company.com/api/v1/userwhitelist/{userwhitelistId}
where {userwhitelistId} is the ID of a user whitelist rule.
Supported methods and overview
GET - used to retrieve information about an existing user whitelist rule, based on the rule's ID.PUT - used to modify the description of an existing user whitelist rule.DELETE - used to delete an existing user whitelist rule.
Note: The GET and DELETE methods take no parameters.
Detailed description
This API endpoint serves a number of purposes:
- Retrieves information about an existing user whitelist rule, based on the user whitelist rule's ID. This ID can be obtained by calling the
GET method of the <access-service>/api/v1/userwhitelist API endpoint, which retrieves a list of field information for all current user whitelist rules on the Covata Platform.
Tip: All information returned in the response from a GET method call to this API endpoint is also returned in the response from a GET method call to the <access-service>/api/v1/userwhitelist endpoint. Therefore, if you do not already have a user whitelist rule's ID and you called the <access-service>/api/v1/userwhitelist endpoint to retrieve it, then there is no need to subsequently call the GET method on this API endpoint.
- Modifies the description of an existing user whitelist rule, based on the user whitelist rule's ID.
Note: It is not possible to modify a user whitelist rule's domain pattern or email address (i.e. the rule itself) as this has the equivalent impact of deleting the rule and adding a new one.
- Deletes an existing user whitelist rule from the Covata Platform.
Important:
- Deleting a user whitelist rule (except the last one) may disable several Covata user 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 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.
- It is also possible to delete one or more user whitelist rules in a single action by calling the <access-service>/api/v1/userwhitelist/bulk API endpoint.
- Deleting the last user whitelist rule from the Covata Platform results in the user whitelist feature being disabled. When the user whitelist feature is disabled, be aware that:
- Covata user accounts are not disabled by not having a user whitelist rule.
- Directly disabling or re-enabling Covata user accounts has no impact on the user whitelist feature.
- Any LDAP user accounts that were disabled by not matching/complying with a user whitelist rule (when the user whitelist feature was enabled) are automatically re-enabled when the Covata Platform next synchronizes with the LDAP server.
Supported roles
This API endpoint supports the following Covata user roles (as described in the Covata Platform Administrator's Guide):
The Covata Platform's resources available to one of these Covata users (above) is determined by the access token passed in the header of requests to this endpoint.
Required headers
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
The following optional parameters can be sent in the body of the PUT request, each as individual members of a JSON object:
-
pattern - Specify the domain pattern or email address of the user whitelist rule whose description is to be modified.
-
description - .
Example ():
Returns
A JSON-formatted response containing the following members:
