Documentation

Chat

  • Getting Started
  • Installation
  • Core Concepts
  • Escalation System
  • Widget Keys
  • Secret Keys (sk_)
  • REST API
  • Channels & Integrations
  • Messaging Platform API

Voice

  • Voice Agent
  • Setup Guide
  • Phone Numbers
  • Outbound Campaigns

Platform

  • Billing & Pricing
  • Glossary
  • FAQ

Secret Keys (sk_)

Secret keys allow you to access the Sampan REST API from your backend, mobile app, or any server-side environment. Unlike public widget keys (wk_), secret keys skip domain validation and are designed for trusted server-to-server communication.

How Secret Keys Work

When you create a secret key, the full key is displayed once. After that, only a hash is stored — we can't recover it for you. Treat it like a password.

  • Prefixed with sk_ followed by 32 random hex characters
  • Authenticated by hashing the key and matching against the stored hash
  • No domain restrictions — works from any origin
  • Full key shown only once at creation
  • Requires the API Access feature on your plan

Creating a Secret Key

  1. Go to Widget Keys in your dashboard
  2. Click "Create New Widget Key"
  3. Select "Secret" as the key type
  4. Fill in the name, domain, and knowledge base
  5. Click "Create Widget Key"
  6. Copy the full key from the one-time reveal dialog — you won't see it again

Store your secret key in environment variables or a secrets manager. Never commit it to source control or expose it in client-side code.

Key Rotation

You can rotate a secret key from the Widget Keys page. When you rotate:

  • A new key is generated and shown once
  • The old key enters a 7-day grace period — both keys work during this time
  • After 7 days, the old key stops working
  • The old key's hash is stored in the previousKey field for grace period lookups

Public Keys vs Secret Keys

Public Keys (wk_)

  • For browser-based widgets
  • Domain restrictions enforced
  • Full key stored in plaintext
  • Visible in dashboard anytime
  • Sources stripped from API responses

Secret Keys (sk_)

  • For server-to-server use
  • No domain restrictions
  • Only hash stored (never plaintext)
  • Shown once at creation
  • Full sources included in API responses

When to Use Secret Keys

  • Backend services that call the Sampan API on behalf of your users
  • Mobile apps where you proxy API calls through your own server
  • Internal tools and scripts that interact with your knowledge base
  • CI/CD pipelines that test your chatbot responses
  • Third-party integrations that need programmatic access

Ready to transform your customer experience?

Join businesses already using Sampan to serve customers 24/7 and boost revenue with AI.

sampan.club

AI-powered customer service for businesses.

SAMPAN TECH
202603046389 (003825593-A)

Product

© 2026 SAMPAN TECH, trading as Sampan Club (sampan.club). All rights reserved.