Authentication

Two auth models: public keys for client-side storefronts, secret keys for server-side full access.

SDK auth (automatic)

Pass your public key to createCimplifyClient -- the SDK handles the X-API-Key header automatically.

TSX

import { createCimplifyClient } from '@cimplify/sdk'

const client = createCimplifyClient({ publicKey: 'pk_test_...' })
const result = await client.catalogue.getProducts()
// X-API-Key header is set automatically on every request

REST API auth

Include your key in the X-API-Key header.

cURL

curl https://api.cimplify.io/v1/businesses/{business_id}/catalogue/products \
  -H "X-API-Key: sk_test_your_api_key"

# Or use Authorization: Bearer
curl https://api.cimplify.io/v1/businesses/{business_id}/catalogue/products \
  -H "Authorization: Bearer sk_test_your_api_key"

Key types

Prefix	Type	Environment	Usage
`pk_live_`	Public	Production	Client-side, read catalogue + create orders
`pk_test_`	Public	Sandbox	Client-side development
`sk_live_`	Secret	Production	Server-side only, full access with scopes
`sk_test_`	Secret	Sandbox	Server-side development

Never expose secret keys (sk_) in client-side code, public repos, or browser bundles.

Key format

Keys follow the pattern {type}_{environment}_{random} where type is pk or sk and environment is live or test.

curl

pk_test_a1b2c3d4e5f6...   # public, sandbox
sk_live_x9y8z7w6v5u4...   # secret, production

Scopes

Secret keys can be restricted to specific scopes. Public keys have fixed read-only storefront access.

Scope	Description
`catalogue.view`	Read products, categories, variants
`catalogue.manage`	Create, update, delete catalogue items
`orders.view`	Read orders
`orders.manage`	Create, update, cancel orders
`customers.view`	Read customer data
`customers.manage`	Create, update customers
`inventory.view`	Read stock levels
`inventory.manage`	Update inventory
`payments.view`	Read payment information
`payments.manage`	Process payments, refunds
`*`	Full access (all scopes)

Key management

Create, view, and revoke keys at app.cimplify.io/settings/developer. Keys are only displayed once at creation -- store them securely.

Error responses

Status	Code	Cause
`401`	`UNAUTHORIZED`	Missing, invalid, or expired API key
`403`	`FORBIDDEN`	Key lacks the required scope for this endpoint

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have required scope: orders.manage"
  }
}

Best practices

Store secret keys in environment variables, never in source code or client bundles.
Use the minimum scopes your application needs -- avoid * in production.
Develop with test keys first, switch to live only at deploy time.