API Token and Access Guide
Use this guide to safely expose Cloud Waste Scanner API to other machines while keeping token-based protection in place.
Docs > API & Automation > Token Guide
Use this page before automation rollout to confirm local token handling and protected route expectations.
Where to Find the Token
- Open the desktop app and go to Settings > Network.
- Locate API Access Token.
- Copy the token for your automation client.
- If you update token/host/port, save and fully restart the app.
On first startup, if token is empty, the app auto-generates a token in the form cws_<random>.
Host and Port Behavior
Local-only mode
Set API Listen Host to 127.0.0.1.
Only the local machine can call the API.
LAN/open access mode
Set API Listen Host to 0.0.0.0.
Other machines can call the API by IP and port, with bearer token.
Bearer Token Usage
# Full scan (all configured cloud profiles)
curl -k -X POST "https://192.168.1.20:9123/v1/scans" -H "Authorization: Bearer YOUR_API_TOKEN"
# Targeted scan (selected accounts only)
curl -k -X POST "https://192.168.1.20:9123/v1/scans" -H "Authorization: Bearer YOUR_API_TOKEN" -H "Content-Type: application/json" -d '{
"selected_accounts": ["profile_abc123"]
}'All non-status API routes require a valid bearer token, including loopback calls. If Local API HTTPS (Self-Signed) is enabled, use https:// and trust your certificate or use -k for controlled local testing.
Rotation Checklist
- Generate and save a new token in Settings > Network.
- Restart app to apply new security settings.
- Update all automation clients with the new token.
- Delete old token copies from scripts, CI logs, and chat history.
Exposure Modes and Trust Boundary
| Mode | Bind Host | Recommended Use |
|---|---|---|
| Workstation-only | 127.0.0.1 | Single-user scripting on the same machine. |
| Team LAN | 0.0.0.0 | Controlled internal automation with bearer token and firewall controls. |
| Remote site | 0.0.0.0 | Only over VPN/private tunnel and strict source allow-list. |
If Token Exposure Is Suspected
- Generate a new token in Settings and save it immediately.
- Restart the app so new token policy is active for API middleware checks.
- Revoke old credentials in all external automation jobs.
- Review recent automation calls and scan runs for unexpected activity.
Hardening Tips
- Prefer private network/VPN for remote API traffic.
- Keep token in secret stores, not plaintext repos.
- Use host firewall rules to restrict source IPs.
- Rotate token immediately if exposure is suspected.
Share
Generate a local token and verify the auth flow end to end.
Save your first $1,000 before the next billing cycle.