Create an API Key

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.

npm install -g commet
commet login
commet link

commet api-keys create --name "Local development" --expires-in-days 365

{
  "body": {
    "name": "Local development",
    "expiresInDays": 365
  }
}

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.

const key = await commet.apiKeys.create({
  name: "Customer reader",
  permissions: { customer: ["read"] },
})

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:

COMMET_API_KEY=ck_replace_with_your_key

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:

npm install @commet/node

Initialize it in server code after loading the environment:

import { Commet } from "@commet/node"

const apiKey = process.env.COMMET_API_KEY
if (!apiKey) {
  throw new Error("COMMET_API_KEY is required")
}

export const commet = new Commet({ apiKey })

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.

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.