Authentication

The Chariow API uses store API keys to authenticate requests. Each key carries 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.

If you do not choose any scopes, the key receives every scope your team role allows. You can change the scopes of an existing key later without regenerating it.

Making Authenticated Requests

Include your API key in the Authorization header:

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

Scopes

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

Required scope per endpoint

Endpoint	Required scopes
Get Store	`store.read`
List Products, Get Product	`products.read`
Initiate Checkout	`checkout.write`
List Sales, Get Sale	`sales.read`
List Customers, Get Customer	`customers.read` and `customers.pii.read`
List Licenses, Get License, Get Activations	`licenses.read`
Activate License, Revoke License	`licenses.write`
List Discounts, Get Discount	`discounts.read`
List Pulses, Get Pulse	`webhooks.read`
Get Affiliate	`affiliates.read`
Send Invitations	`affiliates.write`

A key can never hold more scopes than the team role of the member who created it, and it loses scopes when that role is downgraded. See Authentication for the full rules.

Security Best Practices

Never expose your API key in client-side code or public repositories.

Grant each key only the scopes its integration needs
Store keys in environment variables
Use different keys for development and production
Rotate keys periodically
Monitor key usage in your dashboard

Authentication Errors

Status	Message	Cause
401	`API key is missing. Please provide a valid API key. Help: https://docs.chariow.com`	Missing `Authorization: Bearer` header
401	`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
403	`This credential is missing the required scope: {scopes}. Update its permissions in your dashboard.`	Key lacks a scope the endpoint requires

A 403 scope error lists the missing scopes in errors.scopes and in the WWW-Authenticate header:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="customers.pii.read"

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

Overview

Store

Products

Checkout

Sales

Customers

Licenses

Discounts

Pulses

Affiliates

Creating an API Key

Making Authenticated Requests

Scopes

Required scope per endpoint

Security Best Practices

Authentication Errors

​Creating an API Key

​Making Authenticated Requests

​Scopes

​Required scope per endpoint

​Security Best Practices

​Authentication Errors

Creating an API Key

Making Authenticated Requests

Scopes

Required scope per endpoint

Security Best Practices

Authentication Errors