Subscription management

To use the subscription management endpoints for managing projects and users under a subscription, you need to:

Be a subscription admin.
Authenticate your requests with a Subscription API key.

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.

Subscription project object

id

required · string · uuid

The project container's internal ID.

name

required · string

The project's name.

is_active

required · boolean

A flag determining whether the project is active.

environments[]

required · array

The project's environments.

Show child attributes

JSON

{
  "id": "a7d24131-b0c5-4dda-ad78-c0b409951493",
  "name": "Sample project",
  "is_active": true,
  "environments": [
    {
      "id": "c9bad3b5-2b91-4df9-9d4a-53d0bf14343b",
      "name": "Production"
    },
    {
      "id": "fcd4e8cb-4577-4bd0-9104-07538b64eef7",
      "name": "Dev"
    }
  ]
}

Subscription user object

id

required · string

The user's internal ID.

first_name

string

The user's first name.

last_name

string

The user's last name.

email

required · string · email

The user's email address.

has_pending_invitation

required · boolean

A flag determining whether the user has any pending invitation to a project.

projects[]

required · array · unique items

The projects to which the user has been invited.

Show child attributes

JSON

{
  "id": "e67eadda-dc58-4bf9-89fc-1dadc0b95858",
  "first_name": "John",
  "last_name": "Doe",
  "email": "jonh.doe@exmaple.com",
  "has_pending_invitation": true,
  "projects": {
    "id": "a7d24131-b0c5-4dda-ad78-c0b409951493",
    "name": "Sample project",
    "environments": {
      "id": "c9bad3b5-2b91-4df9-9d4a-53d0bf14343b",
      "name": "Production",
      "is_user_active": true,
      "last_activity_at": "2021-12-24T12:00:00.7692802Z",
      "collection_groups": {
        "collections": {
          "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
          "codename": "object_codename",
          "external_id": "your-own-custom-identifier"
        },
        "roles": {
          "id": "c11a2c9e-f129-43b8-9cb1-20a7b3746934",
          "name": "Project manager",
          "codename": "project-manager",
          "languages": {
            "id": "00000000-0000-0000-0000-000000000000",
            "external_id": "string",
            "codename": "default",
            "name": "Default language",
            "is_active": true
          }
        }
      }
    }
  }
}

List projects under a subscription

Retrieve a dynamically paginated list of projects under the specified subscription.

This endpoint requires the Subscription API key.

GET

https://manage.kontent.ai/v2/subscriptions/{subscription_id}/projects

Request

Path parameters

subscription_id

required · string

Identifies your subscription.

Header parameters

x-continuation

string

Determines the page of results to retrieve.To get the next page of results, check the pagination object in the API response and set the x-continuation header parameter to the value of the continuation_token property.

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 client = _fileSystemFixture.CreateMockClientWithResponse("SubscriptionUsers.json");

var response = await client.ListSubscriptionUsersAsync();

Response

Status (200)

A dynamically paginated list of projects in the subscription.

projects[]

required · array · unique items

List of projects.

Show child attributes

pagination

object

Information about the next page of results.

Show child attributes

Example responses

200

{
  "projects": {
    "id": "a7d24131-b0c5-4dda-ad78-c0b409951493",
    "name": "Sample project",
    "is_active": true,
    "environments": [
      {
        "id": "c9bad3b5-2b91-4df9-9d4a-53d0bf14343b",
        "name": "Production"
      },
      {
        "id": "fcd4e8cb-4577-4bd0-9104-07538b64eef7",
        "name": "Dev"
      }
    ]
  },
  "pagination": {
    "continuation_token": "W3sidG9rZW4iOiIrUklEOn...",
    "next_page": "https://manage.kontent.ai/v2/your/chosen/list/endpoint"
  }
}

List users under a subscription

Retrieve a dynamically paginated list of users under the specified subscription. Includes the users' assignment to projects, environments, collections, roles, and languages.

This endpoint requires the Subscription API key.

GET

https://manage.kontent.ai/v2/subscriptions/{subscription_id}/users

Request

Path parameters

subscription_id

required · string

Identifies your subscription.

Header parameters

x-continuation

string

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.ListSubscriptionUsersAsync();

Response

Status (200)

A dynamically paginated list of users in the subscription.

users[]

required · array · unique items

The list of users in projects under the specified subscription.

Show child attributes

pagination

required · object

Information about the next page of results.

Show child attributes

Example responses

200

{
  "users": {
    "id": "e67eadda-dc58-4bf9-89fc-1dadc0b95858",
    "first_name": "John",
    "last_name": "Doe",
    "email": "jonh.doe@exmaple.com",
    "has_pending_invitation": true,
    "projects": {
      "id": "a7d24131-b0c5-4dda-ad78-c0b409951493",
      "name": "Sample project",
      "environments": {
        "id": "c9bad3b5-2b91-4df9-9d4a-53d0bf14343b",
        "name": "Production",
        "is_user_active": true,
        "last_activity_at": "2021-12-24T12:00:00.7692802Z",
        "collection_groups": {
          "collections": {
            "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
          },
          "roles": {
            "id": "c11a2c9e-f129-43b8-9cb1-20a7b3746934",
            "name": "Project manager",
            "codename": "project-manager",
            "languages": {
              "id": "00000000-0000-0000-0000-000000000000",
              "external_id": "string",
              "codename": "default",
              "name": "Default language",
              "is_active": true
            }
          }
        }
      }
    }
  },
  "pagination": {
    "continuation_token": "W3sidG9rZW4iOiIrUklEOn...",
    "next_page": "https://manage.kontent.ai/v2/your/chosen/list/endpoint"
  }
}

Retrieve a user

Retrieve metadata about a specified user under the specified subscription. The metadata includes information about the user's access to projects and environments, and content in specific collections, roles, and languages.

This endpoint requires the Subscription API key.

GET

https://manage.kontent.ai/v2/subscriptions/{subscription_id}/users/{user_identifier}

Request

Path parameters

subscription_id

required · string

Identifies your subscription.

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).

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("Joe.Joe@kontent.ai");
//var identifier = UserIdentifier.ById("usr_0vKjTCH2TkO687K3y3bKNS");

var response = await client.GetSubscriptionUserAsync(identifier);

Response

Status (200)

A single user object.

id

required · string

The user's internal ID.

first_name

string

The user's first name.

last_name

string

The user's last name.

email

required · string · email

The user's email address.

has_pending_invitation

required · boolean

A flag determining whether the user has any pending invitation to a project.

projects[]

required · array · unique items

The projects to which the user has been invited.

Show child attributes

Example responses

200
404

{
  "id": "e67eadda-dc58-4bf9-89fc-1dadc0b95858",
  "first_name": "John",
  "last_name": "Doe",
  "email": "jonh.doe@exmaple.com",
  "has_pending_invitation": true,
  "projects": {
    "id": "a7d24131-b0c5-4dda-ad78-c0b409951493",
    "name": "Sample project",
    "environments": {
      "id": "c9bad3b5-2b91-4df9-9d4a-53d0bf14343b",
      "name": "Production",
      "is_user_active": true,
      "last_activity_at": "2021-12-24T12:00:00.7692802Z",
      "collection_groups": {
        "collections": {
          "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
        },
        "roles": {
          "id": "c11a2c9e-f129-43b8-9cb1-20a7b3746934",
          "name": "Project manager",
          "codename": "project-manager",
          "languages": {
            "id": "00000000-0000-0000-0000-000000000000",
            "external_id": "string",
            "codename": "default",
            "name": "Default language",
            "is_active": true
          }
        }
      }
    }
  }
}

Activate a user in all projects

Activates the specified user in all projects under the specified subscription.

This endpoint requires the Subscription API key.

PUT

https://manage.kontent.ai/v2/subscriptions/{subscription_id}/users/{user_identifier}/activate

Request

Path parameters

subscription_id

required · string

Identifies your subscription.

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).

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");

await client.ActivateSubscriptionUserAsync(identifier);

Response

Status (204)

The user was activated in all projects under the specified subscription.

Empty response

Example responses

400
404

{
  "request_id": "02e2f665c547564d",
  "error_code": 229,
  "message": "The user 'sso_32c0ad0f-4f5e-4c4c-96ea-d1ed41024d79' is a subscription admin. They cannot be activated or deactivated in all projects."
}

Deactivate a user in all projects

Deactivates the specified user in all projects under the specified subscription.

This endpoint requires the Subscription API key.

PUT

https://manage.kontent.ai/v2/subscriptions/{subscription_id}/users/{user_identifier}/deactivate

Request

Path parameters

subscription_id

required · string

Identifies your subscription.

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).

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");

await client.DeactivateSubscriptionUserAsync(identifier);

Response

Status (204)

User was deactivated in all projects of your subscription.

Empty response

Example responses

400
404

{
  "request_id": "02e2f665c547564d",
  "error_code": 229,
  "message": "This user with ID '5bbf48135624682e96bb8c21' is subscription admin and cannot be activated or deactivated in all projects."
}

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:

Subscription project object

id

required · string · uuid

The project container's internal ID.

name

required · string

The project's name.

is_active

required · boolean

A flag determining whether the project is active.

environments[]

required · array

The project's environments.

Show child attributes

JSON

{
  "id": "a7d24131-b0c5-4dda-ad78-c0b409951493",
  "name": "Sample project",
  "is_active": true,
  "environments": [
    {
      "id": "c9bad3b5-2b91-4df9-9d4a-53d0bf14343b",
      "name": "Production"
    },
    {
      "id": "fcd4e8cb-4577-4bd0-9104-07538b64eef7",
      "name": "Dev"
    }
  ]
}

Subscription user object

id

required · string

The user's internal ID.

first_name

string

The user's first name.

last_name

string

The user's last name.

email

required · string · email

The user's email address.

has_pending_invitation

required · boolean

A flag determining whether the user has any pending invitation to a project.

projects[]

required · array · unique items

The projects to which the user has been invited.

Show child attributes

JSON

{
  "id": "e67eadda-dc58-4bf9-89fc-1dadc0b95858",
  "first_name": "John",
  "last_name": "Doe",
  "email": "jonh.doe@exmaple.com",
  "has_pending_invitation": true,
  "projects": {
    "id": "a7d24131-b0c5-4dda-ad78-c0b409951493",
    "name": "Sample project",
    "environments": {
      "id": "c9bad3b5-2b91-4df9-9d4a-53d0bf14343b",
      "name": "Production",
      "is_user_active": true,
      "last_activity_at": "2021-12-24T12:00:00.7692802Z",
      "collection_groups": {
        "collections": {
          "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53",
          "codename": "object_codename",
          "external_id": "your-own-custom-identifier"
        },
        "roles": {
          "id": "c11a2c9e-f129-43b8-9cb1-20a7b3746934",
          "name": "Project manager",
          "codename": "project-manager",
          "languages": {
            "id": "00000000-0000-0000-0000-000000000000",
            "external_id": "string",
            "codename": "default",
            "name": "Default language",
            "is_active": true
          }
        }
      }
    }
  }
}

// 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 client = _fileSystemFixture.CreateMockClientWithResponse("SubscriptionUsers.json"); var response = await client.ListSubscriptionUsersAsync();

{ "projects": { "id": "a7d24131-b0c5-4dda-ad78-c0b409951493", "name": "Sample project", "is_active": true, "environments": [ { "id": "c9bad3b5-2b91-4df9-9d4a-53d0bf14343b", "name": "Production" }, { "id": "fcd4e8cb-4577-4bd0-9104-07538b64eef7", "name": "Dev" } ] }, "pagination": { "continuation_token": "W3sidG9rZW4iOiIrUklEOn...", "next_page": "https://manage.kontent.ai/v2/your/chosen/list/endpoint" } }

{ "users": { "id": "e67eadda-dc58-4bf9-89fc-1dadc0b95858", "first_name": "John", "last_name": "Doe", "email": "jonh.doe@exmaple.com", "has_pending_invitation": true, "projects": { "id": "a7d24131-b0c5-4dda-ad78-c0b409951493", "name": "Sample project", "environments": { "id": "c9bad3b5-2b91-4df9-9d4a-53d0bf14343b", "name": "Production", "is_user_active": true, "last_activity_at": "2021-12-24T12:00:00.7692802Z", "collection_groups": { "collections": { "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53" }, "roles": { "id": "c11a2c9e-f129-43b8-9cb1-20a7b3746934", "name": "Project manager", "codename": "project-manager", "languages": { "id": "00000000-0000-0000-0000-000000000000", "external_id": "string", "codename": "default", "name": "Default language", "is_active": true } } } } } }, "pagination": { "continuation_token": "W3sidG9rZW4iOiIrUklEOn...", "next_page": "https://manage.kontent.ai/v2/your/chosen/list/endpoint" } }

// 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("Joe.Joe@kontent.ai"); //var identifier = UserIdentifier.ById("usr_0vKjTCH2TkO687K3y3bKNS"); var response = await client.GetSubscriptionUserAsync(identifier);

{ "id": "e67eadda-dc58-4bf9-89fc-1dadc0b95858", "first_name": "John", "last_name": "Doe", "email": "jonh.doe@exmaple.com", "has_pending_invitation": true, "projects": { "id": "a7d24131-b0c5-4dda-ad78-c0b409951493", "name": "Sample project", "environments": { "id": "c9bad3b5-2b91-4df9-9d4a-53d0bf14343b", "name": "Production", "is_user_active": true, "last_activity_at": "2021-12-24T12:00:00.7692802Z", "collection_groups": { "collections": { "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53" }, "roles": { "id": "c11a2c9e-f129-43b8-9cb1-20a7b3746934", "name": "Project manager", "codename": "project-manager", "languages": { "id": "00000000-0000-0000-0000-000000000000", "external_id": "string", "codename": "default", "name": "Default language", "is_active": true } } } } } }

// 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"); await client.ActivateSubscriptionUserAsync(identifier);

{ "request_id": "02e2f665c547564d", "error_code": 229, "message": "The user 'sso_32c0ad0f-4f5e-4c4c-96ea-d1ed41024d79' is a subscription admin. They cannot be activated or deactivated in all projects." }

// 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"); await client.DeactivateSubscriptionUserAsync(identifier);