Skip to main content
The Store API uses three authentication mechanisms depending on the use case: API keys for all requests, JWT tokens for authenticated customers, and order tokens for guest checkout.

​
API Key (Required)

Every request to the Store API requires a publishable API key. This key identifies your storefront and is safe to use in client-side code. Pass the key via the X-Spree-Api-Key header: 
import { createSpreeClient } from '@spree/sdk'

const client = createSpreeClient({
  baseUrl: 'http://localhost:3000',
  publishableKey: 'spree_pk_xxx',
})

// The SDK automatically sends the publishable key with every request
const products = await client.store.products.list()
Publishable API keys are prefixed with spree_pk_. You can create them in the Spree Admin under Settings > API Keys or via the Spree CLI: 
spree api-key create       # Create a new API key
spree api-key list         # List existing API keys
If you omit the API key, the API returns a 401 Unauthorized error:
{
  "error": {
    "code": "invalid_token",
    "message": "Valid API key required"
  }
}

​
JWT Token (Authenticated Customer)

For actions that require a logged-in customer (viewing orders, managing addresses, saved payment methods), use a JWT bearer token in addition to the API key.

​
Login

// Login to get a JWT token
const { token, user } = await client.store.auth.login({
  email: 'customer@example.com',
  password: 'password123',
})

// Use the token for authenticated requests
const orders = await client.store.orders.list({}, { token })

​
Register

const { token, user } = await client.store.auth.register({
  email: 'new@example.com',
  password: 'password123',
  password_confirmation: 'password123',
  first_name: 'John',
  last_name: 'Doe',
})

​
Token Refresh

JWT tokens expire after 1 hour by default. Use the refresh endpoint to get a new token: 
const { token } = await client.store.auth.refresh({ token: currentToken })

​
Order Token (Guest Checkout)

For guest checkout flows, use the order token returned when creating a cart. This allows unauthenticated users to manage their cart and complete checkout. Pass the token via the X-Spree-Order-Token header or order_token query parameter: 
// Create a cart (guest)
const cart = await client.store.cart.create()

// Use orderToken for all cart operations
const options = { orderToken: cart.token }

// Add items
await client.store.orders.lineItems.create(cart.id, {
  variant_id: 'variant_abc123',
  quantity: 1,
}, options)

​
Associating a Guest Cart

After a guest user logs in, you can associate their guest cart with their account: 
await client.store.cart.associate({
  token: jwtToken,
  orderToken: cart.token,
})

​
Authentication Summary

MethodHeaderUse Case
API KeyX-Spree-Api-Key: spree_pk_xxxAll requests (required)
JWT TokenAuthorization: Bearer <token>Authenticated customer actions
Order TokenX-Spree-Order-Token: <token>Guest cart and checkout