API Authentication

The CheckoutOS API uses API keys for authentication. This guide covers how to generate keys, authenticate requests, and manage API access securely.

API Keys

API keys are used to authenticate all requests to the CheckoutOS API. Each key is tied to your store and has configurable permissions.

Generating API Keys

Navigate to Settings

Go to CheckoutOS → Settings → API.

Create New Key

Click "Create API Key".

Name Your Key

Give it a descriptive name (e.g., "Production Server").

Set Permissions

Choose which API scopes the key can access.

Copy Key

Copy the key immediately — it won't be shown again.

Key Security

API keys are only shown once when created. Store them securely. If lost, you'll need to generate a new key.

Authentication Methods

Bearer Token (Recommended)

Include the API key as a Bearer token in the Authorization header:

Bearer Token Authentication

curl -X GET "https://api.chargezen.com/v1/checkoutos/upsells" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

X-API-Key Header

Alternatively, use the X-API-Key header:

X-API-Key Authentication

curl -X GET "https://api.chargezen.com/v1/checkoutos/upsells" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

API Permissions

API keys can be scoped to specific permissions:

Available Scopes

{
  "scopes": {
    "read:upsells": "View upsell configurations",
    "write:upsells": "Create and modify upsells",
    "read:bundles": "View bundle configurations",
    "write:bundles": "Create and modify bundles",
    "read:analytics": "Access analytics data",
    "read:orders": "View order data",
    "write:orders": "Modify orders (edits)",
    "read:settings": "View CheckoutOS settings",
    "write:settings": "Modify settings",
    "webhooks:manage": "Create and manage webhooks"
  }
}

Least Privilege

Only grant the permissions your integration needs. A key for analytics dashboards shouldn't have write access to upsells.

Rate Limiting

API requests are rate limited to ensure fair usage:

Rate Limits

{
  "rate_limits": {
    "requests_per_minute": 120,
    "requests_per_hour": 3600,
    "burst_limit": 20
  },
  "headers": {
    "X-RateLimit-Limit": "120",
    "X-RateLimit-Remaining": "115",
    "X-RateLimit-Reset": "1640000000"
  }
}

When rate limited, you'll receive a 429 response:

Rate Limit Response

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 45 seconds.",
    "retry_after": 45
  }
}

Environments

CheckoutOS provides separate environments for development and production:

API Environments

{
  "production": {
    "base_url": "https://api.chargezen.com/v1",
    "key_prefix": "live_"
  },
  "sandbox": {
    "base_url": "https://sandbox.api.chargezen.com/v1",
    "key_prefix": "test_"
  }
}

Sandbox Environment

Use sandbox for development and testing. Sandbox data is separate from production and can be reset at any time.

Official SDKs

Official SDKs handle authentication automatically:

Node.js SDK

import { CheckoutOS } from '@chargezen/checkoutos-sdk';

const client = new CheckoutOS({
  apiKey: process.env.CHARGEZEN_API_KEY,
  environment: 'production'
});

const upsells = await client.upsells.list();

Python SDK

from chargezen import CheckoutOS

client = CheckoutOS(
    api_key=os.environ['CHARGEZEN_API_KEY'],
    environment='production'
)

upsells = client.upsells.list()

Key Management

Best Practices

Use environment variables — Never hardcode keys
Rotate keys regularly — At least quarterly
Use separate keys per environment — Dev, staging, production
Revoke unused keys — Delete keys no longer in use
Monitor key usage — Watch for anomalous patterns
Use minimal scopes — Only grant needed permissions

Revoking Keys

Navigate to API Settings

Go to CheckoutOS → Settings → API.

Find the Key

Locate the key to revoke in the list.

Revoke

Click "Revoke" and confirm.

Immediate Effect

Key revocation is immediate. Any requests using the revoked key will fail. Make sure you've updated your applications before revoking.

API Reference

API Endpoints

Available API endpoints

Learn more

Webhooks

Real-time event notifications

Learn more