Authentication

The Chariow API uses store API keys to authenticate requests. Each key belongs to one store and carries a set of scopes that decide which endpoints it can call.

Creating an API Key

Go to app.chariow.com and log in to your account.

Navigate to Settings

Click on Settings in the sidebar.

Open API Keys

Select API Keys from the settings menu.

Create New Key

Click Create API Key, give it a descriptive name, choose its scopes, and copy the generated key.

Copy your API key immediately after creation. For security reasons, the full key is only shown once.

API keys start with sk_. Store them as opaque strings: do not parse them or rely on their length.

Scopes

Every public API endpoint requires one or more scopes. Grant each key only the scopes its integration needs: a key that only reads products cannot start a checkout or revoke a licence, even if it leaks.

Available scopes

Scope	Label	Grants access to
`store.read`	Read store	Store name, currency, settings and public information.
`products.read`	Read products	Products, prices and their published details.
`sales.read`	Read sales	Sales, their status and amounts.
`customers.read`	Read customers	Customer list and purchase history.
`customers.pii.read`	Read customer contact details	Customer email addresses and phone numbers. Includes `customers.read`.
`discounts.read`	Read discounts	Discount codes and their conditions.
`licenses.read`	Read licences	Licence keys and their activations.
`licenses.write`	Manage licences	Activate and revoke licence keys. Includes `licenses.read`.
`affiliates.read`	Read affiliates	Affiliate profiles and codes.
`affiliates.write`	Invite affiliates	Send affiliate invitations. Includes `affiliates.read`.
`webhooks.read`	Read webhooks	Pulse webhooks configured on the store.
`webhooks.write`	Manage webhooks	Create and delete the Make, Zapier and n8n connections. Includes `webhooks.read`.
`checkout.write`	Create checkouts	Start a checkout for a product on behalf of a customer.

A write scope always includes its read scope, so granting licenses.write also grants licenses.read.

Scopes required by each endpoint

Endpoint	Required scopes
`GET /v1/store`	`store.read`
`GET /v1/products`, `GET /v1/products/{productId}`	`products.read`
`POST /v1/checkout`	`checkout.write`
`GET /v1/sales`, `GET /v1/sales/{saleId}`	`sales.read`
`GET /v1/customers`, `GET /v1/customers/{customerId}`	`customers.read` and `customers.pii.read`
`GET /v1/licenses`, `GET /v1/licenses/{licenseKey}`, `GET /v1/licenses/{licenseKey}/activations`	`licenses.read`
`POST /v1/licenses/{licenseKey}/activate`, `POST /v1/licenses/{licenseKey}/revoke`	`licenses.write`
`GET /v1/discounts`, `GET /v1/discounts/{discountId}`	`discounts.read`
`GET /v1/pulses`, `GET /v1/pulses/{pulseId}`	`webhooks.read`
`GET /v1/affiliates/{affiliateCode}`	`affiliates.read`
`POST /v1/affiliates/invitations`	`affiliates.write`

The customer endpoints return contact details, so they need both customer scopes. Granting customers.pii.read alone is enough, because it includes customers.read.

How scopes are assigned

Choosing scopes: pick the scopes when you create the key. If you do not pick any, the key receives every scope your team role allows.
Changing scopes: you can change the scopes of an existing key from Settings → API Keys without regenerating it. Integrations using the key keep working with the new permissions.
Team roles: a key can never hold more than the role of the team member who creates it. For example, a member with the Support role cannot grant licenses.write, checkout.write, affiliates.write or webhooks.write.
Role changes: if the creator’s role is downgraded, their keys lose the scopes the new role no longer allows. Promoting the creator does not add scopes to existing keys.
Deactivated members: when a team member loses access to the store, the API keys and MCP connections they created are deleted and stop working immediately. Reactivating the member does not restore them.
Existing keys: keys created before scopes were introduced received every scope their creator’s role allowed at the time.
New scopes: scopes added to the catalogue later are never granted automatically to existing keys. Add them to a key yourself when an integration needs them.

Making Authenticated Requests

Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET "https://api.chariow.com/v1/store" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.chariow.com/v1/store', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('https://api.chariow.com/v1/store', headers=headers)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.chariow.com/v1/store');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);

Key Security Best Practices

Grant the Fewest Scopes

Give each key only the scopes its integration needs. A reporting script needs sales.read, not licenses.write.

Use Environment Variables

Store API keys in environment variables, not in your codebase:

# .env file
CHARIOW_API_KEY=your_api_key

# Access in your code
process.env.CHARIOW_API_KEY

Use Different Keys for Environments

Create separate API keys for development, staging, and production environments. This limits the impact if a key is compromised.

Rotate Keys Regularly

Periodically create new keys and delete old ones. This limits the window of opportunity for compromised keys.

Monitor Key Usage

Regularly review your API key usage in the dashboard. Look for unusual patterns that might indicate unauthorised access.

Restrict Server-Side Only

Never expose your API key in client-side code (JavaScript running in browsers). All API calls should be made from your server.

Authentication Errors

If the key is missing or invalid, you’ll receive a 401 Unauthorised response:

{
  "message": "API key is missing. Please provide a valid API key. Help: https://docs.chariow.com",
  "errors": []
}

Message	Cause	Solution
`API key is missing. Please provide a valid API key. Help: https://docs.chariow.com`	No `Authorization: Bearer` header	Add the header to your request
`Invalid API key. Please check again. Help: https://docs.chariow.com`	Key is malformed, was deleted, or its creator is no longer an active team member	Check the key, or create a new one in your dashboard

Scope Errors

If the key is valid but lacks a scope the endpoint requires, you’ll receive a 403 Forbidden response that lists the missing scopes:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="checkout.write"

{
  "message": "This credential is missing the required scope: checkout.write. Update its permissions in your dashboard.",
  "data": [],
  "errors": {
    "scopes": ["checkout.write"]
  }
}

errors.scopes lists every missing scope. Use it, rather than the message, in your code: the message is translated into the request language.
The WWW-Authenticate header carries the same scopes, separated by spaces.
To fix it, add the missing scopes to the key in Settings → API Keys, or ask a team member whose role allows them.

Rate Limiting

API keys are subject to rate limiting to ensure fair usage:

100 requests per minute per API key for all endpoints except checkout
100 requests per minute per API key for POST /v1/checkout, counted separately

When rate limited, you’ll receive a 429 Too Many Requests response. See Rate Limits for details.

Need higher rate limits? Contact our support team at support@chariow.com.

Next Steps

API Reference

Explore the complete API documentation

Rate Limits

Learn more about rate limiting

Introduction

Guides

MCP Integration

n8n Integration

Resources

Creating an API Key

Scopes

Available scopes

Scopes required by each endpoint

How scopes are assigned

Making Authenticated Requests

Example Request

Key Security Best Practices

Authentication Errors

Scope Errors

Rate Limiting

Next Steps

API Reference

Rate Limits

​Creating an API Key

​Scopes

​Available scopes

​Scopes required by each endpoint

​How scopes are assigned

​Making Authenticated Requests

​Example Request

​Key Security Best Practices

​Authentication Errors

​Scope Errors

​Rate Limiting

​Next Steps

API Reference

Rate Limits

Creating an API Key

Scopes

Available scopes

Scopes required by each endpoint

How scopes are assigned

Making Authenticated Requests

Example Request

Key Security Best Practices

Authentication Errors

Scope Errors

Rate Limiting

Next Steps