Skip to main content

​
Authentication

All API requests require authentication via a Bearer token in the Authorization header. 
Authorization: Bearer sk_test_your_api_key

​
API Key Types

Prefix: sk_live_* or sk_test_*Server-side keys with full access to both Admin and Storefront APIs. Must never be exposed in client-side code.
curl https://api.headlesscommerce.io/v1/admin/products \
  -H "Authorization: Bearer sk_test_your_secret_key"

​
Test vs Live Mode

API keys determine the data mode automatically:
ModeKey PrefixDescription
Testsk_test_*, pk_test_*Sandbox data, no real payments processed
Livesk_live_*, pk_live_*Production data, real transactions
Both modes use the same API base URL. The key prefix determines the mode.
Always develop and test with test mode keys first. Switch to live keys only when ready for production.

​
Customer Authentication (Storefront)

For Storefront endpoints that require customer identity (/customers/me, /orders): Step 1. Your server generates a customer token using the Admin API: 
curl -X POST https://api.headlesscommerce.io/v1/admin/customers/{id}/token \
  -H "Authorization: Bearer sk_test_your_secret_key"
Step 2. The response contains a JWT token: 
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2025-01-16T10:30:00Z"
}
Step 3. Pass this token from the client via the X-Customer-Token header: 
curl https://api.headlesscommerce.io/v1/storefront/customers/me \
  -H "Authorization: Bearer pk_test_your_key" \
  -H "X-Customer-Token: eyJhbGciOiJIUzI1NiIs..."

​
Guest Cart

Carts can be created without customer authentication using a session_id. When a guest customer logs in, merge the guest cart into their account using POST /storefront/carts/{id}/merge.