Skip to main content
ChainStream employs multiple security mechanisms to protect API access. This document covers API security best practices, common threat protection, and security configuration guidelines.
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

Access Token Generation

Credential Security

Storage Requirements
Client Secret is a core credential for accessing ChainStream services. Leakage may result in service abuse and financial loss.

Code Examples

Multi-App Management

We recommend creating separate Apps for different environments and services:

Transport Security

TLS Requirements

Certificate Validation

Never skip certificate validation in production environments. This exposes your application to man-in-the-middle attack risks.

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
View Path: Dashboard → Metrics

Security Monitoring

🚧 Coming Soon — Security monitoring features are under development and will be available soon.
Once available, it will support:
  • 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.
Once available, it will support:
  • 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

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
  • 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

Immediately log into Dashboard to delete that App, create a new App, then update all application configurations using that credential. See Credential Leak Response.
Access Tokens are valid for 24 hours. Recommendations:
  1. Cache Token — Reuse the same Token within validity period
  2. Refresh Early — Refresh Token about 1 hour before expiration
  3. Error Retry — Automatically get new Token when receiving 401 error
Log into Dashboard → Metrics, where you can view request IP, status codes, latency, Units consumed, and time-dimension charts.
Common causes:
  1. Secret mismatch — Confirm using the correct Webhook Secret
  2. Payload handling error — Ensure using the original JSON string for signature calculation
  3. Missing signature header — Confirm request headers include X-Webhook-Signature
Yes. We recommend creating separate Apps for different environments (production/test) and different services for easier management and troubleshooting.

Authentication

Authentication and credential management

Data Privacy

Data privacy policy

Error Codes

Complete error code list

Webhook Fundamentals

Webhook configuration and usage