Contact Secrets

Contact secrets enable secure connections between contacts and external services by managing authentication credentials and OAuth flows. This system allows your AI agents to access external APIs and services on behalf of individual contacts, providing personalized experiences that leverage users' own accounts and data sources.

The secret management system supports multiple authentication methods including OAuth 2.0 authorization flows and API key-based authentication, with built-in security features like access control validation and encrypted credential storage.

Authenticating Contact Secrets

The authentication operation initiates the OAuth flow or credential exchange process for a contact secret, returning an authentication URL that the contact must visit to grant permissions. This endpoint is the first step in connecting a contact's external account to your platform, enabling subsequent API calls to be made on their behalf.

To start the authentication process for a contact secret, send a POST request to the authenticate endpoint:

POST /api/v1/contact/{contactId}/secret/{secretId}/authenticate
Content-Type: application/json

{}

http

Authentication Flow

The authentication process varies based on the secret type:

OAuth Secrets: For secrets configured with OAuth providers, the endpoint returns an authorization URL where the contact must grant permissions. The URL includes all necessary OAuth parameters including client ID, redirect URI, scopes, and state parameter for security.

API Key Secrets: For API key-based secrets, the endpoint validates that the secret is properly configured and returns a direct authentication URL or configuration interface.

Response Format

The endpoint returns the secret ID and authentication URL:

{
  "id": "secret_abc123",
  "url": "https://provider.com/oauth/authorize?client_id=...&redirect_uri=...&state=..."
}

json

The contact should be redirected to this URL to complete the authentication process. After successful authentication, the external provider will redirect back to your platform with authorization credentials.

Access Control

The authentication endpoint enforces strict access control to ensure security:

  • The authenticated user must own the contact
  • The secret must belong to the specified contact
  • The secret must be accessible according to the defined access rules
  • Users without proper access receive authorization errors

Security Considerations

The authentication flow includes several security mechanisms:

  • State Parameter: OAuth flows include a state parameter to prevent CSRF attacks
  • Access Validation: The system verifies that the requesting user has permission to access the secret
  • Provider Verification: Only registered and approved OAuth providers are supported
  • Credential Encryption: All stored credentials are encrypted at rest

Error Handling

Common error scenarios include:

  • Not Found: Contact or secret doesn't exist
  • Not Authorized: User doesn't have permission to authenticate the secret
  • Conflict: Secret type doesn't support authentication or is already authenticated
  • Configuration Error: Secret is missing required configuration (provider, callback URL, etc.)

Post-Authentication

After the contact completes authentication at the provider's authorization URL, they are redirected back to your platform with credentials. The system automatically:

  1. Exchanges authorization codes for access tokens
  2. Stores encrypted credentials securely
  3. Marks the secret as verified and ready to use
  4. Makes the secret available for API calls on behalf of the contact

Important Notes:

  • Authentication URLs are temporary and typically expire after a short period (usually 10-15 minutes)
  • OAuth state parameters are single-use to prevent replay attacks
  • Secrets must be created with appropriate provider and configuration before authentication
  • Re-authenticating an existing secret will refresh credentials and permissions
  • Some providers require specific scopes to be requested during authentication
  • The contact must grant all requested permissions for authentication to succeed

Revoking Contact Secrets

When you need to disconnect a contact's integration or remove their access to an external service, the revoke endpoint permanently invalidates the secret and terminates the authentication relationship.

POST /api/v1/contact/{contactId}/secret/{secretId}/revoke
Content-Type: application/json

{}

http

Revoking a secret performs several important actions:

  • Invalidates the secret: The secret can no longer be used for authentication
  • Revokes OAuth tokens: For OAuth-based secrets, the access token is revoked with the provider
  • Cleans up associations: Removes the secret's connection to the contact
  • Maintains audit trail: The revocation action is logged for security tracking

When to Revoke Secrets

You should revoke contact secrets in several scenarios:

  • Security concerns: If a secret may have been compromised or exposed
  • User request: When a contact wants to disconnect an integration
  • Service changes: When switching to a different authentication method
  • Account cleanup: When removing unused or obsolete integrations
  • Access control: When a contact should no longer have access to a service

OAuth Token Revocation

For secrets that use OAuth 2.0 authentication, the revocation process includes notifying the OAuth provider to invalidate the access token. This ensures that:

  • The token becomes immediately invalid at the provider level
  • No further API requests can be made using the revoked token
  • The contact must go through the full OAuth flow again to reconnect

The revocation request is sent to the OAuth provider's token revocation endpoint as defined in the OAuth 2.0 specification (RFC 7009), ensuring proper cleanup on both the ChatBotKit side and the external service side.

Revocation Response

Upon successful revocation, the endpoint returns the ID of the revoked secret:

{
  "id": "secret_abc123"
}

json

After revocation, the secret cannot be used for any authentication operations, and the contact will need to authenticate again to restore integration functionality.

Important: Revocation is permanent and cannot be undone. The contact must complete the authentication flow again to create a new secret if they want to reconnect the integration. Any AI agents or automations using the revoked secret will no longer be able to access the external service on behalf of the contact.

Verifying Contact Secret Status

Before using a contact secret for integration purposes, you can verify its current authentication status and determine whether the contact needs to complete or refresh their authentication with the external service.

POST /api/v1/contact/{contactId}/secret/{secretId}/verify
Content-Type: application/json

{}

http

The verification endpoint checks the secret's current state and returns detailed information about its authentication status, helping you build robust integrations that gracefully handle authentication requirements.

Understanding Verification Responses

The verification response indicates whether the secret is currently valid and ready to use for authentication, or whether additional action is required from the contact:

Authenticated Status:

{
  "id": "secret_abc123",
  "status": "authenticated"
}

json

When a secret is authenticated, it contains valid credentials and can be immediately used for API requests to the external service. No further action is needed from the contact.

Unauthenticated Status:

{
  "id": "secret_abc123",
  "status": "unauthenticated",
  "action": {
    "type": "authenticate",
    "url": "https://auth.example.com/oauth/authorize?..."
  }
}

json

When unauthenticated, the response includes an action object with a URL where the contact should be redirected to complete the authentication flow. This typically leads to an OAuth authorization page or API key setup form.

Integration Flow Patterns

The verify endpoint enables several useful integration patterns:

Pre-Integration Check: Before attempting to use a secret for an integration, verify its status to ensure authentication is current. This prevents integration failures due to expired or invalid credentials.

Lazy Authentication: When a user first tries to use an integration, verify the secret and redirect them to authenticate only if needed. This creates a smooth user experience where authentication happens on-demand.

Health Monitoring: Periodically verify secrets to detect when credentials expire or are revoked, allowing you to proactively notify users before integration failures occur.

Handling Token Expiration

For OAuth-based secrets, tokens can expire over time. The verify endpoint attempts to detect expired tokens and will return an unauthenticated status when refresh is needed. Some OAuth secrets may support automatic token refresh, while others require the user to re-authorize.

The verification process includes:

  • Credential retrieval: Attempts to retrieve the secret's credentials
  • Validation: Checks if credentials are present and appear valid
  • Error handling: Gracefully handles authentication errors
  • URL generation: Creates an authentication URL when re-auth is needed

Building User Interfaces

The verify endpoint is particularly useful for building user interfaces that show integration status. You can:

  • Display whether an integration is connected and active
  • Show when authentication is required or has expired
  • Provide direct links for users to authenticate or re-authenticate
  • Implement connection health indicators in your application

Important: Verification does not modify the secret or its state. It's a read-only operation that safely checks authentication status without risking changes to the integration configuration. Use the authenticate endpoint to actually establish or refresh authentication.

Listing Contact Secrets

To retrieve all secrets associated with a specific contact, use the list endpoint which returns all authentication tokens, API keys, and OAuth credentials that have been configured for that contact's integrations.

GET /api/v1/contact/{contactId}/secret/list
Content-Type: application/json

http

This endpoint provides visibility into which external services a contact has authenticated with, making it easy to manage and audit their connected integrations. Each secret in the list includes basic information without exposing the actual secret values for security purposes.

Understanding Secret Types

Contact secrets can be of various types depending on the authentication method used by the external service:

  • OAuth tokens: Access and refresh tokens from OAuth 2.0 flows
  • API keys: Direct API key authentication for services that use token-based auth
  • Custom credentials: Service-specific authentication mechanisms

The response includes metadata about each secret, including:

{
  "items": [
    {
      "id": "secret_abc123",
      "name": "Google Calendar Access",
      "description": "OAuth token for calendar integration",
      "type": "oauth",
      "createdAt": "2025-11-20T10:00:00Z",
      "updatedAt": "2025-11-22T15:30:00Z"
    }
  ]
}

json

Pagination and Filtering

Like other list endpoints, contact secret listing supports pagination through cursor-based navigation:

GET /api/v1/contact/{contactId}/secret/list?take=20&order=desc
Content-Type: application/json

http

You can also filter secrets by metadata using the meta query parameter to find secrets with specific attributes or properties.

Security Considerations

The list endpoint returns secret metadata but never exposes actual secret values, tokens, or credentials. This ensures that:

  • Listing secrets doesn't compromise security
  • Audit trails can be maintained without exposing sensitive data
  • User interfaces can display integration status without secret access

To actually use a secret for authentication, you must use the authenticate endpoint with the specific secret ID. To remove access, use the revoke endpoint to invalidate the secret and disconnect the integration.

Important: Secrets are tied to specific contacts and cannot be shared between contacts. Each contact must authenticate separately with external services to create their own secrets for personalized integrations.

Go to cbk.ai