←back to docs

Secrets

Secrets provides a secure environment for storing sensitive information such as tokens, keys, and credentials used across the ChatBotKit services. As a safeguard against exposure to external threats and to preserve data privacy, Secrets ensures that sensitive details remain protected within a secure vault. This feature is allowing customers to integrate and utilize secrets seamlessly within Skillset Abilities and other parts of the ChatBotKit Platform.

Key Features

Enhanced Security

Secrets serve as a secure vault where sensitive data is stored safely, ensuring that crucial information like tokens and credentials used for operating services and APIs are safeguarded from unauthorized access.

Seamless Integration

Within the ChatBotKit platform, Secrets can be easily referenced in Skillset Abilities. This integration simplifies the process of performing secure actions and requests by seamlessly substituting sensitive information with placeholders in code, thereby enhancing functionality without compromising security.

Data Privacy

The implementation of Secrets ensures that sensitive data required to perform actions never leaves the secure vault. It prevents any exposure of sensitive information to the underlying model or external entities, maintaining strict data confidentiality.

Secret Types

There are 5 secret types: plain, basic, bearer, oauth and template. Depending on the secret type, the system will use the correct session initialisation, headers and other supporting information to fulfil the request where the secret is assigned.

Here is a detailed view of each secret type:

TypeDescription
plainA plain secret is a secret value that is provided as is without any subsequent special handling or transformations. It is ideal for custom simple authentication mechanism as well as situations where a custom authentication system is in place.
basicSimilar to basic authentication, the secret is encoded in base64 format with prefix Basic .
bearerThe secret is provided as is but prefix with Bearer when added to the Authorization header.
oauthThe system will perform OAuth authentication and authorization flow. You must provide oauth configuration information.
templateA secret that is instantiated from a template. The template could be a secret corresponding to one of the 4 main types.

OAuth Secrets

When creating OAuth Secrets you must provide a OAuth configuration. The easiest way to create an OAuth secret is via a Blueprint or one of the available templates. The configuration can be expressed as a YAML / JSON object that has the following structure:

clientId: 'YOUR CLIENT ID'
clientSecret: 'YOUR CLIENT SECRET'
tokenUrl: https://service/oauth/token
authorizationUrl: https://service/oauth/authorize
revokeUrl: https://service/oauth/revoke
scope: |
  scope1
  scope2

The revokeUrl is not required but you can specify it if it is available by the upstream provider.

Once you setup the secret you will also need to setup a callback URL. The standard callback URL for all secrets that support oauth is:

"https://chatbotkit.com/secrets/${secretId}/oauth/callback"

Secret Kind

Secrets can be either authenticated by a developer, think of service account, or individual users. For this reason there are two distinct secret kinds: shared and personal.

KindDescription
SharedCorresponds to a secret that is authenticated by a developer and it is shared with the agent and the users of the agent. This is often the case where the remote system does not support multi-user accounts and thus there is a singular credentials for API access.
PersonalCorresponds to a secret that must be authenticated by each user. This is often the case when dealing with multi-user systems where each user has unique permissions and access to specific resources. For example, if you want to allow the agent to act on behalf of user you will use the personal kind.

How To Use Secrets

To utilize the Secrets within ChatBotKit, follow these simple steps:

  1. Storing Secrets:
    • Navigate to the Secrets vault and securely store your sensitive information such as API keys, tokens, or credentials.
  2. Referencing Secrets in Skillset Abilities:

    • When creating or modifying a Skillset Ability that requires sensitive information, reference the stored secret in the action code using the syntax ${SECRET_NAME}. This placeholder is replaced at runtime with the actual secret value, ensuring secure access and use. Here is an example of referencing a secret in a Skillset Ability by name:

      ```fetch
method: POST
url: https://api.example.com/v1/database/search
headers:
  Authorization: ${SECRET_MY_API_TOKEN}
  Content-Type: application/json
body:
  query: $[query ys!|the search phrase or string]
```

    • It also possible to reference a default secret. The default secret is a secret that is directly connected to an ability. This is useful especially in the case of blueprints. To reference the default secret simply is ${SECRET_DEFAULT} syntax). Here is an example of referencing a default secret:

      ```fetch
method: POST
url: https://api.example.com/v1/database/search
headers:
  Authorization: ${SECRET_DEFAULT}
  Content-Type: application/json
body:
  query: $[query ys!|the search phrase or string]
```
securitysecrets