Skip to main content

​
Customer Authentication

For Storefront endpoints that require customer identity (/customers/me, /orders), customers authenticate via JWT tokens.
For API key types and basic authentication, see the Introduction.

​
Customer JWT Flow

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: 
const cart = await client.carts.create({
  session_id: 'guest-session-123',
});
When a guest customer logs in, merge the guest cart into their account: 
// After customer authenticates, merge guest cart
await client.carts.merge(guestCart.id, {
  customer_token: customerToken,
});
See the Cart Merging recipe for a complete implementation.