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 or Flex 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.

Try the Kontent.ai APIs in Postman collection! Our Postman collection is regularly updated and contains endpoints for all Kontent.ai APIs.

We recommend that you fork the Kontent.ai APIs collection. Forking lets you stay up to date by pulling updates when needed.

Once you import the collection, you can start sending requests. Make sure to use environment variables for API keys.

Postman environments are sets of variables with specific values. You can use these variables everywhere in your requests in Postman.

For instance, the Kontent.ai APIs collection comes with an environment called Kontent.ai APIs sample values. The environment specifies a variable named environment_id, which is used in all requests. To get started quickly, we recommend you change the environment_id value to the ID of your own environment.

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

• JavaScript/TypeScript SDK
• .NET SDK

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

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.

Before the API key expires, we'll send an email notification to the API key's owner.

• If the expiration date is less than a day apart from the API key's creation date, the email notification is sent immediately.
• If the expiration date is between 1–7 days apart form the API key's creation date, the email notification is sent 1 day before the expiration date.
• If the expiration date is more than a week apart from the API key's creation date, the email notification is sent 1 week before the expiration date.

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.

The API key inherits the permissions of the user who creates it. For example, if you have permission 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 an 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.

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.

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.

The requests made to Subscription API count towards the overall API calls limit set in the Fair Use Policy or your subscription plan.

There is no limit on the total number of API calls you can make.

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

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.

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.

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

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.

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

• Use a subscription with an Enterprise plan.
• Be a subscription admin.
• Authenticate your requests with a Subscription API key.

Management API and Subscription API together provide combined capabilities to manage users' access and assignments to your projects under a specified subscription.

Under a specified subscription, you can manage your users via Subscription API which enables you to:

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

You can also use Management API to invite users and change user roles in your projects.