Last Updated: February 2026 | Version: v2.0
Authentication Security
Access Token Mechanism
ChainStream uses an OAuth 2.0-based authentication mechanism. You generate a JWT Access Token using your Client ID and Client Secret for API authentication. Authentication Flow: Credential SpecificationsAccess Token Generation
Credential Security
Storage RequirementsCode Examples
Multi-App Management
We recommend creating separate Apps for different environments and services:Transport Security
TLS Requirements
Certificate Validation
Webhook Security
Webhook messages use a signature mechanism to ensure message source reliability.Signature Verification
When you receive a Webhook message, you need to verify the signature using your Webhook Secret to confirm the message is from ChainStream and has not been tampered with.Verification Example
Webhook Secret Rotation
To rotate your Webhook Secret:1
Generate New Secret
Dashboard → Webhooks → Select Endpoint → Rotate Secret
2
Update Application Config
Update to the new Webhook Secret in your application
3
Verify Signature
Confirm the new Secret correctly verifies signatures
Usage Monitoring
Metrics Dashboard
In the Dashboard’s Metrics panel, you can view API and WebSocket call statistics:Chart Data
The Metrics panel provides charts at multiple time dimensions:- Hourly — View call trends for the last 24 hours
- Daily — View call trends for the last 30 days
- Monthly — View historical monthly statistics
Security Monitoring
🚧 Coming Soon — Security monitoring features are under development and will be available soon.
- Anomaly Detection — Auto-detect auth failure spikes, unusual geography, etc.
- Alert Notifications — Email and Webhook alerts
- Auto Protection — Temporary bans, rate limiting, etc.
IP Whitelist
🚧 Coming Soon — IP whitelist feature is under development and will be available soon.
- Single IP configuration (e.g.,
203.0.113.50) - IP range configuration (e.g.,
203.0.113.0/24) - Multiple IPs (comma-separated)
Common Attack Protection
Man-in-the-Middle Attack
Attack Method: Attacker intercepts communication between client and server. Protection Measures:Injection Attack
Attack Method: Attacker attempts unauthorized operations through malicious input data. Protection Measures:Credential Leak Response
If you suspect your Client Secret has been leaked, immediately execute the following steps:1
Delete App Immediately
Dashboard → Apps → Select App → Delete
2
Create New App
Dashboard → Apps → Create New App
3
Update Application Config
Update to new Client ID and Secret in all applications using the old credential
4
Check Metrics
Dashboard → Metrics → Check for abnormal calls
5
Review Security Practices
Investigate leak cause and improve security measures
Security Error Codes
Authentication Related
Access Control Related
Webhook Related
Error Response Example
Security Configuration Checklist
Basic Configuration (Required)
- Use HTTPS for API access
- Store Client ID and Client Secret in environment variables or secret management service
- Don’t commit credentials to code repository
- Use different Apps for production/test environments
- Properly verify Webhook signatures
Advanced Configuration (Recommended)
- Integrate secret management service (AWS Secrets Manager / HashiCorp Vault)
- Regularly check Metrics dashboard for call statistics
- Create separate Apps for different services
Enterprise Configuration (Optional)
- Integrate SIEM system for log analysis
- Establish security incident response process
FAQ
What should I do if my Client Secret is leaked?
What should I do if my Client Secret is leaked?
Immediately log into Dashboard to delete that App, create a new App, then update all application configurations using that credential. See Credential Leak Response.
What if my Access Token expires?
What if my Access Token expires?
Access Tokens are valid for 24 hours. Recommendations:
- Cache Token — Reuse the same Token within validity period
- Refresh Early — Refresh Token about 1 hour before expiration
- Error Retry — Automatically get new Token when receiving 401 error
How do I view API call statistics?
How do I view API call statistics?
Log into Dashboard → Metrics, where you can view request IP, status codes, latency, Units consumed, and time-dimension charts.
How do I troubleshoot Webhook signature verification failures?
How do I troubleshoot Webhook signature verification failures?
Common causes:
- Secret mismatch — Confirm using the correct Webhook Secret
- Payload handling error — Ensure using the original JSON string for signature calculation
- Missing signature header — Confirm request headers include
X-Webhook-Signature
Can I create multiple Apps?
Can I create multiple Apps?
Yes. We recommend creating separate Apps for different environments (production/test) and different services for easier management and troubleshooting.
Related Documentation
Authentication
Authentication and credential management
Data Privacy
Data privacy policy
Error Codes
Complete error code list
Webhook Fundamentals
Webhook configuration and usage

