Users

Users are specific people who have been invited to your Kontent.ai project and its environments.

To manage users via Management API, you need a personal API key with the Invite and manage project members permission.

User object

user_id

required · string · read-only

The user's internal ID.

collection_groups[]

required · array

Specifies the permissions the user has in the environment based on the user's role and access to specific collections and languages.

Show child attributes

JSON

{
  "user_id": "d94bc87a-c066-48a1-a910-4f991ccc1fb5",
  "collection_groups": {
    "collections": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      {
        "codename": "collection-1"
      }
    ],
    "roles": {
      "id": "f58733b9-520b-406b-9d45-eb15a2baee96",
      "languages": [
        {
          "codename": "english"
        }
      ]
    }
  }
}

User management

Use Management API and Subscription API together to manage user access and assignments to your projects under a specified subscription. With Subscription API, you can:

List users under a subscription in your projects and environments.
Retrieve a user to see their metadata.
Manage access to all your projects by activating or deactivating a user.

With Management API, you can:

Invite users to your projects.
Change user roles.

Invite a user

Invite a new user to your project and assign them a specific role. The user becomes active in the environment you invite them to and deactivates in other environments.If you invite a user as a Project manager, the user gains access to all environments in a given project.

The endpoint requires a personal API key with the Invite and manage project members permission.

POST

https://manage.kontent.ai/v2/projects/{environment_id}/users

Request

Path parameters

environment_id

required · string

Identifies your environment.

Body schema

Application/json

The user to be invited.

email

required · string · email

The user's email address.

collection_groups[]

required · array · min. 1 items

Specifies the permissions the user has in the environment based on the user's role and access to specific collections and languages.You can assign the user specific roles in different collections. At least one collection group must be specified.

Show child attributes

Request samples

C#
cURL

// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net
using Kontent.Ai.Management;

var client = new ManagementClient(new ManagementOptions
{
    ApiKey = "KONTENT_AI_MANAGEMENT_API_KEY",
    EnvironmentId = "KONTENT_AI_ENVIRONMENT_ID"
});

var response = await client.InviteUserIntoProjectAsync(new UserInviteModel
{
    CollectionGroup = new List<UserCollectionGroup>
    {
        new UserCollectionGroup
        {
            Collections = new List<Reference>
            {
                Reference.ById(Guid.Empty),
                Reference.ById(Guid.Parse("28b68213-d636-4b01-9fd1-988b93789e17"))
            },
            Roles = new List<Role>
            {
                new Role
                {
                    Id = Guid.Parse("f58733b9-520b-406b-9d45-eb15a2baee96"),
                    Languages = new List<Reference>() { Reference.ById(Guid.Parse("7df9a691-cf29-402d-9598-66273e7561b7")) }
                }
            }
        }
    }
});

Response

Status (201)

An invitation was sent to the user.

user_id

required · string · read-only

The user's internal ID.

collection_groups[]

required · array

Specifies the permissions the user has in the environment based on the user's role and access to specific collections and languages.

Show child attributes

Example responses

201
400

{
  "user_id": "d94bc87a-c066-48a1-a910-4f991ccc1fb5",
  "collection_groups": {
    "collections": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      {
        "codename": "collection-1"
      }
    ],
    "roles": {
      "id": "f58733b9-520b-406b-9d45-eb15a2baee96",
      "languages": [
        {
          "codename": "english"
        }
      ]
    }
  }
}

Change a user's role

Change the user's role and their access to content based on the user's assignment to roles, collections, and languages.

The endpoint requires a personal API key with the Invite and manage project members permission.

PUT

https://manage.kontent.ai/v2/projects/{environment_id}/users/{user_identifier}/roles

Request

Path parameters

environment_id

required · string

Identifies your environment.

user_identifier

required · string

Identifies the user by their internal ID (e.g., mB9I0b-n-Zhe-x2my4NPjJovOiE0cqKgIyuVjqfKyW0) or email (e.g., email/user@example.com).

Body schema

Application/json

User role, collection, and language assignments to be updated.

collection_groups[]

required · array · min. 1 items · unique items

Hide child attributes

collections[]

required · array · unique items

Specifies the collections the user has access to.Provide either references to collections, or an empty array to assign the user to all collections.

Hide child attributes

id

string · uuid

The referenced object's internal ID.

codename

string · write-only

The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.

external_id

string · write-only

The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.

roles[]

required · array · min. 1 items

The roles the user is assigned to in a collection group. At least one role must be specified.

Hide child attributes

id

required · string · uuid

The role's internal ID.

languages[]

required · array · unique items

Specifies the languages the user has access to.Provide either references to languages, or an empty array to assign the user to all languages.

Hide child attributes

id

string · uuid

The referenced object's internal ID.

codename

string · write-only

The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.

external_id

string · write-only

The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.

Request samples

C#
cURL

// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net
using Kontent.Ai.Management;

var client = new ManagementClient(new ManagementOptions
{
    ApiKey = "KONTENT_AI_MANAGEMENT_API_KEY",
    EnvironmentId = "KONTENT_AI_ENVIRONMENT_ID"
});

var identifier = UserIdentifier.ByEmail("user@kontent.ai");
//var identifier = UserIdentifier.ById("d94bc87a-c066-48a1-a910-4f991ccc1fb5");

var response = await client.ModifyUsersRolesAsync(
    identifier,
    new UserModel
    {
        CollectionGroup = new List<UserCollectionGroup>
        {
            new UserCollectionGroup
            {
                Collections = new List<Reference>
                {
                    Reference.ById(Guid.Empty),
                },
                Roles = new List<Role>
                {
                    new Role
                    {
                        Id = Guid.Parse("f58733b9-520b-406b-9d45-eb15a2baee96"),
                        Languages = new List<Reference>() { Reference.ByCodename("english") }
                    }
                }
            }
        }
    });

Response

Status (200)

The user's roles were updated.

user_id

required · string · read-only

The user's internal ID.

collection_groups[]

required · array

Specifies the permissions the user has in the environment based on the user's role and access to specific collections and languages.

Show child attributes

Example responses

{
  "user_id": "d94bc87a-c066-48a1-a910-4f991ccc1fb5",
  "collection_groups": {
    "collections": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      {
        "codename": "collection-1"
      }
    ],
    "roles": {
      "id": "f58733b9-520b-406b-9d45-eb15a2baee96",
      "languages": [
        {
          "codename": "english"
        }
      ]
    }
  }
}

User object

user_id

required · string · read-only

The user's internal ID.

collection_groups[]

required · array

Specifies the permissions the user has in the environment based on the user's role and access to specific collections and languages.

Show child attributes

JSON

{
  "user_id": "d94bc87a-c066-48a1-a910-4f991ccc1fb5",
  "collection_groups": {
    "collections": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      {
        "codename": "collection-1"
      }
    ],
    "roles": {
      "id": "f58733b9-520b-406b-9d45-eb15a2baee96",
      "languages": [
        {
          "codename": "english"
        }
      ]
    }
  }
}

User management

Use Management API and Subscription API together to manage user access and assignments to your projects under a specified subscription.

With Subscription API, you can:

With Management API, you can:

// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net using Kontent.Ai.Management; var client = new ManagementClient(new ManagementOptions { ApiKey = "KONTENT_AI_MANAGEMENT_API_KEY", EnvironmentId = "KONTENT_AI_ENVIRONMENT_ID" }); var response = await client.InviteUserIntoProjectAsync(new UserInviteModel { CollectionGroup = new List<UserCollectionGroup> { new UserCollectionGroup { Collections = new List<Reference> { Reference.ById(Guid.Empty), Reference.ById(Guid.Parse("28b68213-d636-4b01-9fd1-988b93789e17")) }, Roles = new List<Role> { new Role { Id = Guid.Parse("f58733b9-520b-406b-9d45-eb15a2baee96"), Languages = new List<Reference>() { Reference.ById(Guid.Parse("7df9a691-cf29-402d-9598-66273e7561b7")) } } } } } });

{ "user_id": "d94bc87a-c066-48a1-a910-4f991ccc1fb5", "collection_groups": { "collections": [ { "id": "00000000-0000-0000-0000-000000000000" }, { "codename": "collection-1" } ], "roles": { "id": "f58733b9-520b-406b-9d45-eb15a2baee96", "languages": [ { "codename": "english" } ] } } }

// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net using Kontent.Ai.Management; var client = new ManagementClient(new ManagementOptions { ApiKey = "KONTENT_AI_MANAGEMENT_API_KEY", EnvironmentId = "KONTENT_AI_ENVIRONMENT_ID" }); var identifier = UserIdentifier.ByEmail("user@kontent.ai"); //var identifier = UserIdentifier.ById("d94bc87a-c066-48a1-a910-4f991ccc1fb5"); var response = await client.ModifyUsersRolesAsync( identifier, new UserModel { CollectionGroup = new List<UserCollectionGroup> { new UserCollectionGroup { Collections = new List<Reference> { Reference.ById(Guid.Empty), }, Roles = new List<Role> { new Role { Id = Guid.Parse("f58733b9-520b-406b-9d45-eb15a2baee96"), Languages = new List<Reference>() { Reference.ByCodename("english") } } } } } });