CommetCommet
GitHubDiscordStatus
Introduction

Quickstart

Create an API KeyQuickstart

Learn

Resources

SDK ReferenceAPI VersioningError HandlingTestingCLIExamples

Plugins

Better Auth
DocumentationKnowledge BaseBuild with AIAPI ReferenceWebhooks

Create an API Key

Create a sandbox API key from the dashboard, CLI, or MCP, store it on your server, and rotate it safely.

An API key gives your server access to one Commet organization. Start with a sandbox organization while building your integration.

Sandbox and live keys both start with ck_. The organization that created the key determines its environment; you cannot tell sandbox from live by reading the prefix. Both 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. Enter a descriptive name, such as Local development.
  4. 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.

Install the Commet CLI, sign in through your browser, and link the project to your sandbox organization:

npm install -g commet
commet login
commet link

Choose the organization marked sandbox. Linking a new organization generates a key for CLI resource commands and saves it in .commet/config.json. The CLI adds .commet/ to .gitignore. Keep that directory private.

This configures the CLI; it does not set COMMET_API_KEY for your application. To create a separate application key after linking:

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

Save the returned apiKey as described below. Resource commands use COMMET_API_KEY from the environment before the linked project's key, so check which credential is active before creating or deleting keys.

Connect your agent to the Commet MCP server at https://commet.co/mcp/v2. With OAuth, you can sign in through your browser and select a sandbox organization without an existing API key. The connection stays fixed to that organization.

Ask the agent to create an application key using api_create_api_key with these arguments:

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

The response contains the full secret only once. Have the agent store it directly in the intended local secret file or secret manager when your tools support that. Do not paste an existing secret into the conversation or ask the agent to repeat it in a message.

Already authenticating with an API key? You can create replacements with POST /api/v1/api-keys. That request needs an existing key and creates another key for the same organization. See Create API key for the request and response.

Store the key on your server

For local development, save the key in a git-ignored environment file:

.env.local
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.

How is this guide?

Introduction

Measure consumption, manage subscriptions, and accept payments for your SaaS or AI product with Commet.

Quickstart

Go from a Commet account to your first subscription payment in sandbox.

On this page

Create a key
Store the key on your server
Use the key in your SDK
Rotate and promote to live