Subscription API (2)

Download OpenAPI specification:Download

Kontent.ai Support: support@kontent.ai License: MIT Terms of Service

About Subscription API

Subscription API is a secure REST API that provides read and write access to your Kontent.ai project.

Use Subscription API to manage users, roles, and projects under a specific Kontent.ai subscription. You need to be on an Enterprise plan to use the API.

The base URL for Subscription API is https://manage.kontent.ai/v2/subscriptions. Requests must be made securely over HTTPS with TLS 1.2 and authenticated with a valid personal API key. Requests to the API are rate limited and uncached.

Postman collection

Try the Kontent.ai APIs with Postman! 📫 The Postman collection is regularly updated and contains endpoints for all Kontent.ai APIs, just like you see in the API references.

SDKs

We offer the following SDKs to help you interact with Subscription API. However, you don't need an SDK to use the API.

The SDKs for Subscription API are the same as for Management API.

Authentication

Bearer authentication

Subscription API uses OAuth 2.0 bearer token (API key) to authorize requests. Requests with an incorrect or missing Authorization header will fail with an error.

Send your requests over HTTPS and authenticate using the Authorization header in the following format: Authorization: Bearer <YOUR_SUBSCRIPTION_API_KEY>.

The Subscription API key is available only to subscription admins.

  • Provides access to projects and users under a specific subscription.
  • Provides the ability to use any of the Management API and Subscription API endpoints.
  • Dynamically inherits the permissions of the user who creates it.

To get your Subscription API key:

  1. Go to Kontent.ai.
  2. Click your initials in the bottom left corner.
  3. Click Subscriptions.
  4. Select a subscription you want to manage.
  5. In Subscription API, click Copy to clipboard for the Subscription API key.
Security Scheme Type: HTTP
HTTP Authorization Scheme bearer
Bearer format: "<YOUR_SUBSCRIPTION_API_KEY>"

API keys

Regenerate API keys you created before Jan 23, 2023

On Jan 23, 2023, we've introduced new personal API keys. Make sure to use the new API keys in your existing apps.

The API keys created before Jan 23, 2023 have been deprecated and will stop working on April 30, 2023.

Expiration

The API key expiration length is set to 6 months by default. This is also the recommended expiration length.

When creating or regenerating your API keys, you can specify your preferred API key expiration length. The expiration length can vary from 1 minute to 2 years.

Expiration reminder

5 days before the API key's expiration date, we'll send a notification email to users with the Manage APIs permission.

Identity

The API key for Subscription API inherits the identity of the user who generates the key.

Any API operations performed with the key will show in the content item version history and audit log as changes made by the specific user.

Permission

The API key inherits the permissions of the user who creates it. For example, if you have the permissions to only manage API keys and manage taxonomy, the API key you create allows you to use Management API and work only with the taxonomy endpoints. Using such API key with any other endpoints will result in an 403 Unauthorized error.

The permission inheritance is dynamic. The API key permissions are directly tied to the current role of the user who creates it. If your role permissions change, the permissions of your API key change as well. No need to regenerate the API key.

Revocation

If you regenerate your API key before its expiration date, the API key is revoked after a few minutes and you get a new API key. For requests made with a revoked API key, you receive the 403 Unauthorized error. You cannot revoke an API key without generating a new one.

Scope

The scope of the API key is per subscription per user. When you create or regenerate an API key in one of your subscriptions, the API key applies to all projects under the subscription.

API limitations

API requests limit

The requests made to Subscription API count towards the overall API calls limit set in our Fair Use Policy. For more information, see Pricing FAQ on our Kontent.ai website.

Rate limiting

Rate limits specify the number of requests you or your application can make to Subscription API within a specific time window.

There are per second and per minute time frames with different rate limits.

  • 10 requests per second
  • 400 requests per minute

Avoid parallel requests

We strongly advise against making multiple requests to the API in parallel. This may cause unpredictable behavior and lead to inconsistencies in your content. We recommend that you wait for each request to finish before sending another one.

When you reach the limit of a specific time window, the API will reject the request and respond with the 429 HTTP error.

{
    "request_id": "80000004-0002-fd00-b63f-84710c7967bb",
    "error_code": 10000,
    "message": "API rate limit exceeded. Please retry your request later."
}

The error response will include the Retry-After header that tells you how many seconds you need to wait before attempting further requests. Each failed request is perfectly safe to retry.

If you begin to receive 429 HTTP errors, reduce the frequency of your requests.

Errors

The API returns standard HTTP status codes to indicate the success or failure of a request. In general, status codes in the 2xx range indicate a successful request, status codes in the 4xx range indicate errors caused by an incorrect input (for example, providing incorrect API key), and status codes in the 5xx range indicate an error on our side.

HTTP status codes summary

Status code Description
400 Bad Request The request was not understood. Check your request for a missing required parameter or an invalid query parameter value.
401 Unauthorized The provided API key expired, is in the wrong format, or is missing. Try copying and using the current API key for your project.
403 Forbidden The provided API key is valid but doesn't provide permission for the specified resource.
404 Not Found The requested resource doesn't exist. Try checking the resource name for typos.
405 Method Not Allowed The requested HTTP method is not supported for the specified resource.
429 Too Many Requests The rate limit for the API has been exceeded. Try your request again after a few seconds as specified in the Retry-After header.
5xx Internal Error or Service Unavailable Something went wrong on our side. Try your request again after a few seconds and use a retry policy.

Resolving errors

For troubleshooting failed requests, the API provides error messages defined in a consumable format to help you identify and fix the issue.

request_id
required
string <uuid>

The performed request's unique ID.

error_code
required
integer <int32> >= 0

The specific internal code for the type of error. Only useful for finding patterns among error requests.

message
required
string

The error message explaining why the error occurred.

Array of objects

A list of specific issues that occurred when processing the request.

{
  • "request_id": "|797b0d5e2cecaf41b17a5aa4ca1b9276.d1956d1_",
  • "error_code": 5,
  • "message": "The provided request body is invalid. See the 'validation_errors' attribute for more information and specify a valid JSON object.",
  • "validation_errors": [
    • {
      • "message": "No patch operations were provided, provide at least one operation."
      }
    ]
}

If you cannot identify and resolve an issue with your API call, you can contact us with the response status and the request ID you get in the error response.

Subscription management

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

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.

required
Array of objects

The project's environments.

{
  • "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.

required
Array of objects unique

The projects to which the user has been invited.

{
  • "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": [
        • {
          }
        ]
      }
    ]
}

List projects under a subscription

get/{subscription_id}/projects

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

This endpoint requires Enterprise plan and the Subscription API key.

SecurityBearer authentication
Request
path Parameters
subscription_id
required
string

Identifies your subscription.

Example: c01cbc88-ea9a-4208-852d-3b76406ebbd7
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.

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of projects in the subscription.

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

var client = new ManagementClient(new ManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
});

var client = _fileSystemFixture.CreateMockClientWithResponse("SubscriptionUsers.json");

var response = await client.ListSubscriptionUsersAsync();
Response samples
application/json
{
  • "projects": [
    • {
      • "id": "a7d24131-b0c5-4dda-ad78-c0b409951493",
      • "name": "Sample project",
      • "is_active": "true",
      • "environments": [
        • {
          },
        • {
          }
        ]
      }
    ],
  • "pagination": {}
}

List users under a subscription

get/{subscription_id}/users

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 Enterprise plan and the Subscription API key.

SecurityBearer authentication
Request
path Parameters
subscription_id
required
string

Identifies your subscription.

Example: c01cbc88-ea9a-4208-852d-3b76406ebbd7
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.

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of users in the subscription.

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

var client = new ManagementClient(new ManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
});

var response = await client.ListSubscriptionUsersAsync();
Response samples
application/json
{
  • "users": [
    • {
      • "id": "e67eadda-dc58-4bf9-89fc-1dadc0b95858",
      • "first_name": "John",
      • "last_name": "Doe",
      • "email": "jonh.doe@exmaple.com",
      • "has_pending_invitation": "true",
      • "projects": [
        • {
          }
        ]
      }
    ],
  • "pagination": {}
}

Retrieve a user

get/{subscription_id}/users/{user_identifier}

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 Enterprise plan and the Subscription API key.

SecurityBearer authentication
Request
path Parameters
subscription_id
required
string

Identifies your subscription.

Example: c01cbc88-ea9a-4208-852d-3b76406ebbd7
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).

Example: mB9I0b-n-Zhe-x2my4NPjJovOiE0cqKgIyuVjqfKyW0
Responses
200

A single user object.

404

The specified user was not found.

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

var client = new ManagementClient(new ManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
});

var identifier = UserIdentifier.ByEmail("Joe.Joe@kontent.ai");
//var identifier = UserIdentifier.ById("usr_0vKjTCH2TkO687K3y3bKNS");

var response = await client.GetSubscriptionUserAsync(identifier);
Response samples
application/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": [
        • {
          }
        ]
      }
    ]
}

Activate a user in all projects

put/{subscription_id}/users/{user_identifier}/activate

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

This endpoint requires Enterprise plan and the Subscription API key.

SecurityBearer authentication
Request
path Parameters
subscription_id
required
string

Identifies your subscription.

Example: c01cbc88-ea9a-4208-852d-3b76406ebbd7
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).

Example: mB9I0b-n-Zhe-x2my4NPjJovOiE0cqKgIyuVjqfKyW0
Responses
204

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

400

The user could not be activated in all projects under the specified subscription.

404

The user was not found.

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

var client = new ManagementClient(new ManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
});

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

await client.ActivateSubscriptionUserAsync(identifier);
Response samples
application/json
{
  • "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

put/{subscription_id}/users/{user_identifier}/deactivate

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

This endpoint requires Enterprise plan and the Subscription API key.

SecurityBearer authentication
Request
path Parameters
subscription_id
required
string

Identifies your subscription.

Example: c01cbc88-ea9a-4208-852d-3b76406ebbd7
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).

Example: mB9I0b-n-Zhe-x2my4NPjJovOiE0cqKgIyuVjqfKyW0
Responses
204

User was deactivated in all projects of your subscription.

400

The user could not be deactivated in all projects under the specified subscription.

404

The user was not found.

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

var client = new ManagementClient(new ManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
});

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

await client.DeactivateSubscriptionUserAsync(identifier);
Response samples
application/json
{
  • "request_id": "02e2f665c547564d",
  • "error_code": 229,
  • "message": "This user with ID '5bbf48135624682e96bb8c21' is subscription admin and cannot be activated or deactivated in all projects."
}