Sub-Accounts

Sub-Accounts in Partner API

The Partner (Sub-Accounts) API allows you to manage sub-accounts, which are commonly used for multi-tenant platforms or partner integrations. This guide provides an overview of available endpoints and how to use them with the CBK SDK.

1. Partner User Management

Create a Partner User

Use this endpoint to create a new partner user with basic information such as name and email address.

const user = await cbk.partner.user.create({
  name: 'Partner User',
  email: 'user@example.com'
});

javascript
  • name: Full name of the user.
  • email: User’s email address.

Fetch a Partner User

This endpoint allows you to retrieve detailed information about a specific partner user by providing their unique identifier.

const user = await cbk.partner.user.fetch(userId);

javascript
  • Retrieves a partner user by their userId.

Update a Partner User

Use this endpoint to update specific fields of a partner user, such as their name or email address.

const updatedUser = await cbk.partner.user.update(userId, {
  name: 'Updated Name'
});

javascript
  • Modifies user information.

Delete a Partner User

This endpoint allows you to permanently delete a partner user and all associated data from the system.

await cbk.partner.user.delete(userId);

javascript
  • Removes a partner user permanently.

List Partner Users

Use this endpoint to retrieve a paginated list of all partner users in your system.

const users = await cbk.partner.user.list({ take: 50 });

javascript
  • Lists all partner users with pagination.

2. Partner User Token Management

Create a Partner User Token

Use this endpoint to create an authentication token for a partner user, enabling them to access authorized resources and services.

const token = await cbk.partner.user.token.create(userId);

javascript
  • Generates an access token for the user.

List Partner User Tokens

This endpoint allows you to retrieve a list of all authentication tokens associated with a specific partner user.

const tokens = await cbk.partner.user.token.list(userId);

javascript
  • Retrieves all tokens associated with a user.

Delete a Partner User Token

Use this endpoint to delete a specific authentication token for a partner user, effectively revoking their access to authorized resources.

await cbk.partner.user.token.delete(userId, tokenId);

javascript
  • Revokes a specific token.

3. Setting Sub-Account Limits

When creating partner users, you can set specific usage limits to control their resource consumption. This is particularly useful for managing different tiers of users or implementing usage-based pricing models.

Setting Limits During User Creation

You can specify various limits when creating a new partner user:

const user = await cbk.partner.user.create({
  name: 'Partner User',
  email: 'user@example.com',
  limits: {
    tokens: 1_000_000,    // Maximum tokens allowed
    messages: 10_000,     // Maximum messages allowed
    conversations: 1_000  // Maximum conversations allowed
  }
});

javascript

Available Limit Parameters

  • tokens: Specify the maximum number of tokens the sub-account can use.
  • messages: Set the maximum number of messages the sub-account can send or receive.
  • conversations: Define the maximum number of conversations the sub-account can create.
  • records: Set the maximum number of records the sub-account can store.
  • datasets: Limit the number of datasets the sub-account can create and maintain.
  • files: Control the maximum number of files or attachments allowed.
  • skillsets: Define the number of custom skillsets the sub-account can configure.
  • integrations: Specify the maximum number of third-party integrations allowed.

Updating User Limits

You can also update limits for existing users using the update endpoint:

const updatedUser = await cbk.partner.user.update(userId, {
  limits: {
    tokens: 2_000_000,    // Update token limit
    messages: 20_000,    // Update message limit
    conversations: 2_000  // Update conversation limit
  }
});

javascript

Best Practices for Limit Management

  • Set reasonable default limits based on your service tiers
  • Monitor usage patterns to adjust limits appropriately
  • Implement notifications when users approach their limits
  • Consider implementing graduated limits for different subscription tiers

Note: When a user reaches any of their limits, they will not be able to perform actions that would exceed those limits until the limits are increased or reset.

Conclusion

This guide outlines how to manage sub-accounts and their tokens within Chatbotkit using the Partner API. Proper use of these endpoints facilitates efficient management of multi-tenant environments.

Go to cbk.ai