Skip to main content

How do I create and manage multiple public API keys for different environments?

Last updated 5 min read

Workspace admins can create, name, and revoke up to 25 public API keys under Settings → Public API Keys. Provisioning dedicated public keys for production, staging, and local environments isolates credential rotation so rotating one key never disrupts other integrations. Public keys permit log ingestion and feedback submission, while administrative reads require private credentials.

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:

  1. In the Coolhand dashboard, navigate to Settings → Public API Keys.
  2. Click Create API Key.
  3. 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, or Local Dev - Team Search. Names must be unique within your workspace.
  4. Enter a Description (optional, up to 500 characters) to document ownership, associated repositories, or rotation schedules.
  5. 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:

  1. Navigate to Settings → Public API Keys.
  2. Locate the key and select Regenerate.
  3. Confirm the prompt. Coolhand immediately generates a new ch_pub_... secret and invalidates the previous token.
  4. 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:

  1. Navigate to Settings → Public API Keys.
  2. Click Revoke next to the target key.
  3. 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:

Related articles