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: 1000000, // Maximum tokens allowed messages: 10000, // Maximum messages allowed conversations: 1000 // 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: 2000000, // Update token limit messages: 20000, // Update message limit conversations: 2000 // 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.