Coolhand allows workspace admins to provision and manage multiple public API keys. Instead of sharing a single workspace credential across all deployments, you can create distinct public keys for separate applications, microservices, and deployment tiers such as local development, staging, and production.
If an API key is leaked or retired in a test environment, you can regenerate or revoke that specific key without interrupting ingestion across your production systems or other connected tools.
Why use separate public API keys
Sharing one public API key across every environment creates operational and security risks:
- Isolated credential rotation: If a staging server or developer laptop is compromised, you can revoke or regenerate its key immediately without coordinating downtime across production services.
- Traffic attribution and auditing: Monitoring when each key was last used helps you identify dormant integrations, confirm when newly deployed environments start sending traffic, and audit decommissioning.
- Accidental leakage containment: Embedding keys in frontend builds, CLI hook configurations, or developer workstations carries different exposure risks than server-side production deployments.
Workspaces created prior to multi-key support have their original credential preserved as the Default key, ensuring existing integrations continue operating without reconfiguration.
Creating a public API key
Workspace admins can provision new public API keys directly from the dashboard:
- In the Coolhand dashboard, navigate to Settings → Public API Keys.
- Click Create API Key.
- Enter a Name (required, up to 100 characters). Choose a descriptive name that identifies where the key will live, such as
Production Web App,Staging API Gateway, orLocal Dev - Team Search. Names must be unique within your workspace. - Enter a Description (optional, up to 500 characters) to document ownership, associated repositories, or rotation schedules.
- Click Save. Copy the generated key (formatted as
ch_pub_...) and store it in your environment configuration.
Each workspace can maintain up to 25 public API keys simultaneously.
Managing key lifecycles
The Public API Keys page provides visibility and controls for each provisioned key:
Monitoring activity with Last Used timestamps
Each key in your list displays a Last Used timestamp. Coolhand records usage whenever a key authenticates an API request, updating the timestamp with hourly resolution. If an environment is decommissioned and its key shows no activity for weeks, you can safely retire it.
Regenerating a key
When a key needs routine rotation or has been exposed in a non-production setting:
- Navigate to Settings → Public API Keys.
- Locate the key and select Regenerate.
- Confirm the prompt. Coolhand immediately generates a new
ch_pub_...secret and invalidates the previous token. - Update the key in the target environment. The key's Last Used record resets until the new credential sends its first request.
Regenerating a key only affects services using that exact credential; all other workspace keys remain active.
Revoking a key
When retiring an application, cleaning up ephemeral test environments, or handling a compromised credential:
- Navigate to Settings → Public API Keys.
- Click Revoke next to the target key.
- Confirm the revocation.
Any subsequent API request presenting the revoked key will be rejected immediately with an HTTP 401 Unauthorized response.
Note: A workspace must always retain at least one active public API key. Coolhand prevents you from revoking the last remaining key in your workspace.
Public vs. private key permissions
Coolhand enforces strict privilege separation between public and private API credentials:
| Capability | Public API Key (ch_pub_...) |
Private API Key (ch_priv_...) |
|---|---|---|
Ingest LLM request logs (POST /api/v2/llm_request_logs) |
Allowed (capped at 10 MB payload, 255-character collector) | Allowed (uncapped) |
Submit user feedback (POST & PATCH /api/v2/llm_request_log_feedbacks) |
Allowed (restricted update fields) | Allowed (full update fields) |
Read public inference model catalog (GET /api/v2/inference_apis) |
Allowed | Allowed |
Query or export request logs (GET /api/v2/llm_request_logs) |
Blocked (401 Unauthorized) |
Allowed |
Read feedback records (GET /api/v2/llm_request_log_feedbacks) |
Blocked (401 Unauthorized) |
Allowed |
Read or manage prompt templates (/api/v2/llm_request_templates) |
Blocked (401 Unauthorized) |
Allowed |
| Connect to Model Context Protocol (MCP) server | Blocked | Allowed |
Because public API keys cannot read request logs, prompt contents, or evaluation scores, they are safe to place in distributed environments, client-side feedback widgets, and CLI skill hooks (see How do I capture my agent skills' runs in Coolhand?). Private API keys must be reserved strictly for server-to-server analytics, MCP tools, and administrative automation.
Configuring keys across environments
Set your environment-specific public API key using the standard COOLHAND_API_KEY environment variable across your SDKs and CLI tools:
# In your production environment (.env.production)
COOLHAND_API_KEY=ch_pub_prod_...
# In your staging environment (.env.staging)
COOLHAND_API_KEY=ch_pub_staging_...
# In your local development profile (.env.local)
COOLHAND_API_KEY=ch_pub_dev_...
SDK integrations automatically detect COOLHAND_API_KEY when initializing monitoring:
- Node.js: See Node.js/JavaScript SDK Integration Best Practices for auto-monitoring initialization order.
- Ruby: See Ruby SDK Integration Best Practices for configuring
config.api_keyin Rails or background workers. - REST API: Pass the key in either the
Authorization: Bearer ch_pub_...orX-API-Key: ch_pub_...header.