API Keys

Cimplify uses three families of credentials: **public keys** for the browser SDK, **secret keys** for server-to-server calls, and **developer keys** for the CLI. Each prefix tells you exactly where it belongs.

Key formats

Prefix	Family	Where it runs	Header
`pk_test_…`	Public, sandbox	Browser, mobile, edge	`X-Public-Key`
`pk_live_…`	Public, production	Browser, mobile, edge	`X-Public-Key`
`sk_test_…`	Secret, sandbox	Your backend / functions	`X-API-Key`
`sk_live_…`	Secret, production	Your backend / functions	`X-API-Key`
`dk_…`	Developer key (CLI)	CI machines, scripted deploys	`X-API-Key`

Secret and developer keys must never appear in browser bundles, public repos, or frontend env vars. Anything starting with NEXT_PUBLIC_ is shipped to the browser.

Browser: public keys

The SDK client takes a publicKey. Anything you can do with a public key is safe to do from the browser: read the catalogue, manage a session cart, run the OTP login, hit checkout.

lib/cimplify-client.ts

import { createCimplifyClient } from "@cimplify/sdk";

export const client = createCimplifyClient({
  publicKey: process.env.NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY!,
});

Server: secret keys

Server actions, cron jobs, and webhook receivers use sk_… keys with the X-API-Key header. Scopes (e.g. orders.manage, catalogue.view) are configured per-key in the dashboard.

Direct REST call from a server

curl https://api.cimplify.io/v1/businesses/bus_123/orders \
  -H "X-API-Key: sk_live_••••••••"

For Next.js App Router, prefer getServerClient() from @cimplify/sdk/server; it reads your secret key from the environment and memoises a per-request client.

CLI: developer keys

The cimplify CLI authenticates browser-first via OAuth + PKCE on a loopback redirect, with no key handling at all. For CI environments where you can't pop a browser, mint a developer key (dk_…) in the dashboard and pass it explicitly.

CI authentication

# Local dev (default): browser OAuth, no key on disk
cimplify login

# CI / headless: pass a developer key
cimplify login --api-key dk_••••••••
cimplify deploy --prod

Rotating keys

Every key family supports overlap: create the new key, redeploy with it, then revoke the old one. The SDK reads its public key from the environment, so a redeploy is the only change required on the client side.

# 1. Create the replacement key in the dashboard.
# 2. Push the new value through your env vars.
cimplify env add NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=pk_live_new
cimplify deploy --prod

# 3. Once traffic confirms the new key is live, revoke the old one.

Environments Test mode, sandbox, and live mode
Errors CimplifyError shape and retry rules