API keys and scopes
API keys and scopes
Manage keys in the dashboard at Developer → API → Keys (https://app-dev.clearway.to/developer/api/keys).
Key modes
| Mode | Prefix | Use |
|---|---|---|
| Sandbox / test | clwy_test_… | Dev integrations and playground testing |
| Live | clwy_live_… | Production — moves real money on write operations |
Use Sandbox or test keys when following examples on this site ({docsEnv.keyPrefixExample}).
Scope templates
When creating a key, pick a template that matches your integration:
| Template | Typical use | Notable scopes |
|---|---|---|
| Widget / Checkout | Browser checkout via your server proxy | create:checkout_session, create:payment_link |
| Backend integration | Server-only automation | create:payment_link, read:products, … |
| General | Dashboard-style testing | Broader read + checkout scopes |
Each API operation in the API Reference lists its required scope. Missing scope → 403 FORBIDDEN.
Product writes (CREATE_PRODUCT, UPDATE_PRODUCT, DELETE_PRODUCT) are dashboard-first today. The public API exposes LIST_PRODUCTS and GET_PRODUCT read operations under read:products.
Reserved scopes such as full_access are not assignable from the dashboard.
Origin allowlist (browser-facing keys)
Keys used from browser contexts (widget / checkout flows) can require an allowed origins list. Server-only backend keys typically leave origins empty.
Edit origins on an existing key row in the dashboard, or during creation for widget keys.
Rotation and revocation
- Create a new key with the same scopes.
- Deploy the new secret to your servers.
- Revoke the old key from the dashboard.
Revoked keys remain visible under Inactive keys for audit context.
Security
- Never embed API keys in HTML, mobile apps, or client-side JavaScript.
- Never paste live keys into the docs API Reference playground.
- Widget integrations must use a server proxy — see Checkout integration.
Next steps
- Authentication — how to send the key
- Checkout integration — widget proxy pattern
- API Reference — scope per operation