Canonical URL: https://chargezen.com/docs/checkoutos/api/authentication

# API Authentication

Secure access to the CheckoutOS API

Last updated: 2025-01-16

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

1

#### Navigate to Settings

Go to CheckoutOS → Settings → API.

2

#### Create New Key

Click "Create API Key".

3

#### Name Your Key

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

4

#### Set Permissions

Choose which API scopes the key can access.

5

#### 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

```bash
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

```bash
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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```javascript
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

```python
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

1

#### Navigate to API Settings

Go to CheckoutOS → Settings → API.

2

#### Find the Key

Locate the key to revoke in the list.

3

#### 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



](https://chargezen.com/docs/checkoutos/api/endpoints)[

### Webhooks

Real-time event notifications

Learn more



](https://chargezen.com/docs/checkoutos/api/webhooks)

Was this page helpful?

Need more help? [Contact support](https://chargezen.com/docs/checkoutos/troubleshooting/support)