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 Specifications| Item | Specification |
|---|---|
| Client ID | Application unique identifier |
| Client Secret | 64 random characters |
| Access Token | JWT format, includes expiration and scopes |
| Token Validity | 24 hours |
Access Token Generation
Credential Security
Storage Requirements| Storage Method | Security Level | Notes |
|---|---|---|
| Environment Variables | ✅ Recommended | Not in version control |
| Secret Management Service | ✅ Best | AWS Secrets Manager, HashiCorp Vault, etc. |
| Config Files | ⚠️ Caution | Must add to .gitignore |
| Hardcoded | ❌ Prohibited | High leak risk |
Code Examples
Multi-App Management
We recommend creating separate Apps for different environments and services:| Purpose | Suggested App Name | Description |
|---|---|---|
| Production | prod-main | Production workloads |
| Testing | test-dev | Development and testing |
| CI/CD | ci-pipeline | Automated testing |
| Monitoring | monitoring | Monitoring and alerting |
Transport Security
TLS Requirements
| Item | Requirement |
|---|---|
| Minimum Version | TLS 1.2 |
| Recommended Version | TLS 1.3 |
| Certificate Validation | Must be enabled |
| Not Supported | HTTP, TLS 1.0/1.1 |
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.| Item | Description |
|---|---|
| Algorithm | HMAC-SHA256 |
| Key | Webhook Secret (configured in Dashboard) |
| Signature Header | X-Webhook-Signature |
Verification Example
Webhook Secret Rotation
To rotate your Webhook Secret:Usage Monitoring
Metrics Dashboard
In the Dashboard’s Metrics panel, you can view API and WebSocket call statistics:| Metric | Description |
|---|---|
| Request IP | Source IP address |
| User Agent | Client identifier |
| Status Code | HTTP status code |
| Latency | Request response time |
| Units Consumed | Usage units consumed by this request |
| Total Usage | Cumulative usage consumed |
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:| Measure | Description |
|---|---|
| Enforce HTTPS | Only TLS 1.2+ supported |
| Certificate Validation | Must enable certificate verification |
| HSTS | Force HTTPS connections |
Injection Attack
Attack Method: Attacker attempts unauthorized operations through malicious input data. Protection Measures:| Measure | Description |
|---|---|
| Input Validation | Strict parameter type checking |
| Parameterized Queries | Prevent SQL/NoSQL injection |
| Output Encoding | Prevent XSS |
Credential Leak Response
If you suspect your Client Secret has been leaked, immediately execute the following steps:Update Application Config
Update to new Client ID and Secret in all applications using the old credential
Security Error Codes
Authentication Related
| Error Code | HTTP Status | Description |
|---|---|---|
UNAUTHORIZED | 401 | No authentication provided |
EXPIRED_TOKEN | 401 | Access Token expired |
INVALID_TOKEN | 401 | Access Token invalid |
INVALID_CREDENTIALS | 401 | Client ID or Secret incorrect |
Access Control Related
| Error Code | HTTP Status | Description |
|---|---|---|
FORBIDDEN | 403 | No permission or quota exhausted |
RATE_LIMITED | 429 | Request rate exceeded |
INSUFFICIENT_SCOPE | 403 | Token permission insufficient |
Webhook Related
| Error Code | Description |
|---|---|
INVALID_SIGNATURE | Webhook signature verification failed |
MISSING_SIGNATURE | Missing signature header |
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.

