Managing users in Management API

Managing users in Management API#

This guide explains how to create, list, edit and delete users with the 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 Generating an API key in Adverity.

Prerequisites#

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

  • Obtain a Bearer API key with the user permission. This key can only be generated by a user with Administrator permissions in the root workspace. For more information, see Generating an 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:

    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}}'

Note

User management endpoints only support API keys generated in the Adverity user interface, which use the Bearer scheme in the Authorization header.

Response fields#

The response contains an object for each user with the following fields:

Field

Description

id

The numeric ID of the user.

email

The user’s email address.

first_name

The user’s first name.

last_name

The user’s last name.

active

Boolean. true if the user account is active.

groups

List of group IDs the user belongs to.

workspaces

List of workspace IDs the user has access to.

workspace_names

List of workspace names associated with the user.

created

Timestamp of when the user account was created.

last_login

Timestamp of the user’s most recent login. null if the user has never logged in.

last_modified

Timestamp of the last modification to the user account.

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
}'

Note

User management endpoints only support API keys generated in the Adverity user interface, which use the Bearer scheme in the Authorization header.

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}}'

Note

User management endpoints only support API keys generated in the Adverity user interface, which use the Bearer scheme in the Authorization header.

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
}'

Note

User management endpoints only support API keys generated in the Adverity user interface, which use the Bearer scheme in the Authorization header.

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}}'

Note

User management endpoints only support API keys generated in the Adverity user interface, which use the Bearer scheme in the Authorization header.

Contents