Partner Tokens

Partner tokens provide an alternative authentication mechanism for partner users (sub-accounts) to access the ChatBotKit API programmatically, without requiring user impersonation. These tokens are created by the parent partner account on behalf of their partner users and grant the same level of access as if the partner user created the token themselves. This approach enables partners to provision API access for their customers without requiring customers to directly interact with the ChatBotKit platform.

Creating Partner Tokens

To create an API token for a partner user (sub-account), send a POST request to the partner token creation endpoint. This operation must be performed by the parent partner account and requires the target partner user's ID. The created token will belong to the partner user and grant access to their resources and permissions.

Partner tokens are particularly useful when building integrated solutions where your application needs to perform operations on behalf of customer accounts. For example, you might create tokens during customer onboarding to enable immediate API access, or generate tokens for specific integrations that need to interact with ChatBotKit services.

The API returns the newly created token string along with its ID and creation timestamp. This is the only time the complete token value will be available - it cannot be retrieved again later for security reasons. Store the token securely in your application's configuration or secret management system.

Critical Security Notice: API tokens provide full access to the partner user's account and all their resources. The returned token value (prefixed with sk-) must be treated as a highly sensitive credential. Never expose tokens in client-side code, log files, error messages, or publicly accessible locations. Always transmit tokens over HTTPS and store them encrypted at rest.

Token Usage: The created token can be used in the Authorization header as a Bearer token for all ChatBotKit API requests. When the token is used, all operations are performed within the context of the partner user account, with access to only their resources and subject to their configured limits.

Important: Unlike regular user sessions, API tokens do not expire automatically and remain valid until explicitly deleted. Implement token rotation policies in your application to periodically create new tokens and delete old ones, reducing the risk of compromised credentials being used indefinitely.

Deleting Partner Tokens

To revoke an API token belonging to a partner user (sub-account), send a POST request to the partner token delete endpoint. This operation permanently removes the token from the system, immediately invalidating it and preventing any further API requests using that token. This is the primary mechanism for revoking access when tokens are compromised, no longer needed, or as part of regular token rotation practices.

Token deletion is immediate and irreversible. Once a token is deleted, any applications or integrations using that token will receive authentication errors on their next API request. Ensure you have updated all systems that depend on the token before deletion, or have a process in place to quickly provide replacement tokens.

Security Best Practice: Delete tokens immediately when they are no longer needed, when you suspect they may have been compromised, or as part of regular security hygiene. Implement automated token rotation by creating new tokens and deleting old ones on a scheduled basis (e.g., every 90 days).

Emergency Revocation: If you suspect a token has been leaked or compromised, delete it immediately through this endpoint. The revocation is instantaneous, and the token will be rejected for all subsequent API requests, effectively cutting off unauthorized access.

Operational Note: When deleting tokens that are actively being used by applications or integrations, coordinate the deletion with deployment of updated credentials to minimize service disruption. Consider implementing a brief overlap period where both old and new tokens are valid to enable zero-downtime token rotation.

Important: Only the parent partner account can delete tokens belonging to its partner users. The partner user cannot delete their own tokens through the standard token deletion endpoint - they must use this partner token endpoint or request deletion through the parent account.

Listing Partner Tokens

You can retrieve a list of all API tokens belonging to a specific partner user (sub-account) by sending a GET request to the partner token list endpoint. This operation returns paginated results showing all tokens that have been created for the specified partner user, allowing you to audit API access and manage token lifecycle.

The list endpoint provides essential information about each token including its ID, name, description, metadata, and timestamps for creation and last update. However, for security reasons, the actual token values are never returned in list operations - they are only provided once during token creation.

This endpoint is particularly useful when building administrative interfaces for managing customer API access, auditing token usage, or implementing token rotation workflows. You can display a list of active tokens with their creation dates and metadata to help partners track which tokens are being used for what purposes.

Security Audit: Regularly listing partner tokens allows you to identify unused or orphaned tokens that should be deleted. Long-lived tokens that haven't been rotated represent potential security risks and should be reviewed periodically. Consider implementing automated alerts for tokens that are older than your organization's security policy allows.

Best Practice: Implement a naming convention for partner tokens that indicates their purpose and associated application or integration. For example, use names like "Production API Integration" or "Staging Environment Access" to make token management more intuitive and reduce the risk of accidentally deleting active tokens.