Skip to main content
An API key gives your server access to one Commet organization. Start with a sandbox organization while building your integration. New full-access keys start with ck_sandbox_ or ck_live_; new restricted keys start with rk_sandbox_ or rk_live_. Existing ck_ keys remain valid. The organization that created the key determines which data it can reach. Both environments use https://commet.co/api/v1.

Create a key

Choose the path that fits where you are working. You only need one to get started.
  1. Select your sandbox organization in the dashboard.
  2. Go to Settings → API Keys and click Create API Key.
  3. Choose Full Access for a backend or AI Agents to select resource permissions.
  4. Enter a descriptive name of up to 32 characters, such as Local development, and choose Expires In (Days). The dashboard accepts 1–365 days and defaults to 365.
  5. Create the key and copy it before closing the dialog. The full secret is shown only once.
Already authenticating with a full-access API key? You can create replacements with POST /api/v1/api-keys. That request creates another key for the same organization. See Create API key for the request and response.

Limit key permissions

Leave permissions out to create a full-access key. Provide resource grants to create a restricted key. For example, a key with customer: ["read"] can read customers but cannot change them. Write access requires both "read" and "write". An empty object ({}) grants no resource access. A restricted key with api_key: ["read", "write"] can create restricted keys with the same or fewer permissions. These keys expire no later than the key that creates them. Restricted keys cannot edit or delete API keys.
The full secret is returned once. Save it in your secret store before leaving the response.

Store the key on your server

For local development, save the key in a git-ignored environment file:
.env.local
Load this variable into your server process using your framework’s environment support. For production, use your deployment’s secret store. Never expose the key in browser code, public environment variables, logs, screenshots, or source control. Commet stores a hash of the key and cannot show the full secret again. If you lose it, create a replacement.

Use the key in your SDK

For Node.js, install the SDK:
Initialize it in server code after loading the environment:
For other languages, follow the Python, Go, Java, or PHP integration guide. Direct REST requests authenticate with the x-api-key header.

Rotate and promote to live

Use a separate key for each application or deployment that needs independent rotation. To replace a key before it expires:
  1. Create a replacement in the same organization.
  2. Update the secret in every process using the old key and deploy or restart those processes.
  3. Verify a successful read with the replacement and confirm the application is using it.
  4. Delete the old key from Settings → API Keys or through Delete API key.
A deleted key stops authenticating within about 5 seconds. A key’s last use, Last used in the dashboard and lastUsedAt in List API keys, can lag up to 5 minutes. For production, create a key in your live organization and store it separately from sandbox credentials. Do not copy sandbox customer, plan, or subscription IDs into live configuration. Before switching, verify checkout, webhooks, and a renewal in sandbox with the Test Clock. Next, follow the quickstart to complete your first subscription payment in sandbox.