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
- Go to Widget Keys in your dashboard
- Click "Create New Widget Key"
- Select "Secret" as the key type
- Fill in the name, domain, and knowledge base
- Click "Create Widget Key"
- 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
