Managing users in Management API

Limitations

User management endpoints are only available when using an API key generated in the Adverity user interface. These keys use the Bearer scheme in the Authorization header. For more information, see Creating a Connect API key in Adverity.

Prerequisites

Before you complete the procedures in this guide, perform all of the following actions:

• Use a Connect API key with the following permissions:

  • User: Read-only (user:read) to list and view users.

  • User: Write (user:write) to create, update, or delete users.

  You can select the User permission only on a key for the root workspace, and only if you are an Administrator. Picking Write for a permission also gives the key its Read-only access. Without the permission a request needs, Management API returns HTTP 403. You cannot change the permissions of a key, so to add one, create a new key. For more information, see Creating a Connect API key in Adverity.

Listing existing users

To list existing users, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/v1/users/
   

2. Configure the pagination parameters:

   Scroll horizontally to see the full table.

   Parameter	Default value
   page	1
   page_size	50

   The endpoint with the default parameters looks the following way:

   https://{{INSTANCE}}/api/v1/users/?page=1&page_size=50
   

3. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

4. Send the request.

As a result, you obtain the list of existing users in Management API in the response.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/v1/users/?page=1&page_size=50' \
--header 'Authorization: Bearer {{KEY}}'

Creating a new user

To create a new user, follow these steps:

1. Create a POST request to the following endpoint:

   https://{{INSTANCE}}/api/v1/users/
   

2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the following parameters with their respective values:

   {
       "email": "user@example.com",
       "first_name": "string",
       "last_name": "string",
       "groups": [],
       "workspaces": [],
       "active": true
   }
   

5. Send the request.

As a result, you created a new user through Management API.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request POST 'https://{{INSTANCE}}/api/v1/users/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
-d '{
    "email": "user@example.com",
    "first_name": "string",
    "last_name": "string",
    "groups": [],
    "workspaces": [],
    "active": true
}'

Viewing a user

To view an existing user, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/v1/users/{{user_id}}/
   

2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

3. Send the request.

As a result, you obtain the details of the selected user in Management API in the response.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/v1/users/{{user_id}}/' \
--header 'Authorization: Bearer {{KEY}}'

Editing a user

To edit an existing user, follow these steps:

1. Create a PATCH request to the following endpoint:

   https://{{INSTANCE}}/api/v1/users/{{user_id}}/
   

2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the parameters that you want to update out of the following:

   {
       "email": "user@example.com",
       "first_name": "string",
       "last_name": "string",
       "groups": [],
       "workspaces": [],
       "active": true
   }
   

5. Send the request.

As a result, you updated the selected user through Management API.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request PATCH 'https://{{INSTANCE}}/api/v1/users/{{user_id}}/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
-d '{
    "email": "user@example.com",
    "first_name": "string",
    "last_name": "string",
    "groups": [],
    "workspaces": [],
    "active": true
}'

Deleting a user

To delete an existing user, follow these steps:

1. Create a DELETE request to the following endpoint:

   https://{{INSTANCE}}/api/v1/users/{{user_id}}/
   

2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

3. Send the request.

As a result, you deleted the selected user through Management API.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request DELETE 'https://{{INSTANCE}}/api/v1/users/{{user_id}}/' \
--header 'Authorization: Bearer {{KEY}}'