Platform Secrets

Many abilities and integrations require authentication credentials to access external services such as Google Calendar, Notion, Slack, or custom APIs. The platform provides a secure secret management system that stores and handles these credentials safely, preventing exposure in logs or client-side code.

Understanding Secret Types

To discover which types of credentials and authentication methods are supported by the platform:

GET /api/v1/platform/secret/list

http

Each secret type in the response describes a specific authentication method:

  • id: URL-safe kebab-case slug derived from the template key (e.g., google-oauth)
  • template: The original catalogue identifier for the secret (e.g., google/oauth)
  • name: Human-readable name of the credential type
  • description: Explanation of what service or purpose this secret type serves
  • type: The authentication mechanism (API key, OAuth token, etc.)

Secret Types and Use Cases

Different secret types correspond to different authentication mechanisms:

  • API Keys: Simple authentication tokens for services that use key-based auth
  • OAuth Tokens: Authorization credentials obtained through OAuth flows
  • Service Credentials: Specialized authentication for enterprise services
  • Custom Secrets: User-defined credential types for proprietary integrations
{
  "id": "google-oauth",
  "template": "google/oauth",
  "name": "Google OAuth",
  "description": "OAuth credentials for Google services",
  "type": "oauth2"
}

javascript

Working with Secrets

The secret list endpoint helps you understand which credential types are available when configuring abilities or integrations. When setting up an ability that requires authentication:

  1. Check the ability's documentation to determine which secret type is required
  2. Verify that the necessary secret type is supported by checking this list
  3. Create a secret of the appropriate type through the platform's secret management endpoints
  4. Reference the secret by ID when configuring the ability

Security Best Practices

Secrets are stored securely and encrypted at rest. The platform ensures that:

  • Secret values are never exposed in API responses
  • Secrets are only accessible to authorized resources within your account
  • Secret access is logged for audit purposes
  • Secrets can be rotated without changing ability configurations

Important: This endpoint only lists the types of secrets that are supported by the platform. It does not return actual secret values or the secrets you have created in your account. To manage your actual secrets, use the dedicated secret management endpoints.

Security Warning: Never commit secrets to source control, expose them in client-side code, or share them through insecure channels. Always use the platform's secret management system to handle credentials securely.

Searching Secrets

Semantic search helps you find relevant standard platform secret templates quickly. The endpoint compares your natural language query against pre-generated embeddings and returns ranked results. Use this to discover which secret template to configure before connecting an external service to an ability.

POST /api/v1/platform/secret/search
Content-Type: application/json

{
  "search": "oauth token for google calendar",
  "take": 10
}

http

The search field accepts natural language queries. Describe the service or authentication method you need - for example "Slack bot token", "Jira API key", or "GitHub personal access token". The optional take parameter limits the number of results returned (1-100, default 10).

Secret Search Response Fields

Each item in the items array contains the following fields:

  • id: Kebab-case slug derived from the template key (e.g. google-calendar). Use this as a stable reference.
  • template: The original catalogue key (e.g. google/calendar). Reference this when creating a secret in your account.
  • name: Human-readable name of the secret template.
  • description: Short explanation of what this secret is used for.
  • type: The authentication type. One of plain (API key in query/header), bearer (token in Authorization header), oauth (OAuth2 flow), or template (platform-managed OAuth).
  • kind: The secret scope. shared means it applies across all interactions; personal means it is user-specific.
  • config: Partial OAuth configuration (when applicable) such as authorization and token URLs and required scopes. Sensitive fields like clientId, clientSecret, and password are always stripped from search results.
  • icon: URL or icon reference for displaying in UI.
  • tags: Array of string tags for categorisation.
  • setup: User-facing instructions explaining how to obtain the secret value (e.g. steps to create an API key in the provider's dashboard).
  • commentary: Internal notes about quirks or caveats of this secret template.
  • score: Cosine similarity score between 0 and 1. Higher values indicate a closer semantic match. Scores above 0.7 are typically strong matches.
  • excerpt: Text snippet from the most semantically relevant part of the secret description.
  • link: URL to the full secret template page on the ChatBotKit website.
{
  "items": [
    {
      "id": "google-calendar",
      "template": "google/calendar",
      "name": "Google Calendar",
      "description": "Connect to Google Calendar to access your events.",
      "type": "oauth",
      "kind": "personal",
      "config": {
        "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
        "tokenUrl": "https://oauth2.googleapis.com/token",
        "scope": "https://www.googleapis.com/auth/calendar"
      },
      "tags": ["google", "calendar", "oauth"],
      "score": 0.91,
      "excerpt": "OAuth2 token granting access to Google Calendar events...",
      "link": "https://chatbotkit.com/secrets/google-calendar"
    }
  ]
}

javascript

Security note: Sensitive configuration fields (clientId, clientSecret, password, pass) are always omitted from search results regardless of the secret's configuration.

Go to cbk.ai