API keys and developer access
Cleanbox provides a REST API for programmatic access to your account. This article explains how to enable API access, manage your API key, and what you can do with the API.
Note: The Cleanbox API is currently in development and will be available later this year. The Developer page in the dashboard shows documentation for planned endpoints.
Enabling the API
- Go to Developer in the sidebar
- Toggle Enable API access
When you enable the API, it becomes active for your entire team. All team members share the same API token. Only the team owner can enable or disable API access.
Your API key
After enabling the API, your key is displayed in a masked format (first 8 characters visible). You can:
- Show token — Reveals the full API key. Keep this secret — anyone with the key has access to your team's data.
- Regenerate — Creates a new API key and invalidates the old one. Use this if your key is compromised.
Authentication
All API requests require a Bearer token in the Authorization header:
Authorization: Bearer cb_your_api_key_hereAPI keys use the cb_ prefix for easy identification.
Available endpoints
The API provides read and write access to core Cleanbox resources. When available, the Developer page in the dashboard shows full endpoint documentation with request/response examples for:
- Team — Account and team information
- Contacts — List, search, and manage contacts
- Aliases — List and manage email aliases
- Messages — Query message history
Error handling
All API errors return a consistent JSON format with an error code and message. Common error codes:
| Code | Meaning |
|---|---|
| 401 | Unauthorized — invalid or missing API key |
| 403 | Forbidden — API not enabled or insufficient permissions |
| 404 | Resource not found |
| 429 | Rate limit exceeded — wait before retrying |
| 500 | Server error — contact support if persistent |
Access restrictions
- API access is restricted to the team owner and admins
- Regular team members cannot view or use the API key
- The API is rate-limited to prevent abuse
- All API requests are logged in the activity log
