Authentication

API key types, test/live modes, and customer authentication

Authentication

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

Authorization: Bearer sk_test_your_api_key

API Key Types

Secret Keys

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"

Publishable Keys

Prefix: pk_live_* or pk_test_*

Client-side keys restricted to Storefront API endpoints only. Safe to include in browser or mobile applications.

curl https://api.headlesscommerce.io/v1/storefront/products \
  -H "Authorization: Bearer pk_test_your_publishable_key"

Test vs Live Mode

API keys determine the data mode automatically:

Mode	Key Prefix	Description
Test	sk_test_*, pk_test_*	Sandbox data, no real payments processed
Live	sk_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.