Getting Started
API Authentication

API Authentication

Learn how to create API keys, understand scopes, and securely authenticate your requests to the BareCommerce API.

Overview

BareCommerce uses API keys to authenticate requests. Each key has specific scopes that determine what actions it can perform. This gives you fine-grained control over access.

Key Concepts

  • API Keys — Unique credentials that identify your application
  • Scopes — Permissions that control what each key can access
  • Store ID — Each request targets a specific store

Creating API Keys

Via Dashboard

  1. Go to your store's Settings → API Keys
  2. Click "Create API Key"
  3. Give it a descriptive name (e.g., "Storefront Production")
  4. Select the scopes your key needs
  5. Copy the key immediately — it's only shown once!

⚠️ Important: The full API key is only shown once when created. Store it securely. If you lose it, you'll need to create a new key.

Via API

You can also create API keys programmatically (requires dashboard authentication):

curl -X POST "https://api.barecommercecore.com/stores/{storeId}/api-keys" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -d '{
    "name": "Storefront Production",
    "scopes": ["products:read", "orders:write", "customers:read"]
  }'

API Key Format

BareCommerce API keys follow this format:

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • sk_live_ — Prefix indicating a live/production key
  • xxxxx... — 32-character random string

Available Scopes

Scopes follow the pattern resource:action. Choose the minimum scopes your integration needs.

ScopeAllows
products:readList and view products
products:writeCreate, update, delete products
orders:readList and view orders
orders:writeCreate and update orders
orders:deleteCancel/delete orders
customers:readList and view customers
customers:writeCreate, update, delete customers
categories:readList and view categories
categories:writeCreate, update, delete categories
pages:readList and view pages
pages:writeCreate, update, delete pages
media:readList and view media
media:writeUpload and delete media

Making Authenticated Requests

Include your API key in the Authorization header:

cURL

curl "https://api.barecommercecore.com/stores/{storeId}/products" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

JavaScript

const response = await fetch(
  `https://api.barecommercecore.com/stores/${storeId}/products`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
    },
  }
);
 
const data = await response.json();

Python

import requests
 
response = requests.get(
    f"https://api.barecommercecore.com/stores/{store_id}/products",
    headers={
        "Authorization": f"Bearer {api_key}",
    },
)
 
data = response.json()

Alternative: X-API-Key Header

You can also use the X-API-Key header:

curl "https://api.barecommercecore.com/stores/{storeId}/products" \
  -H "X-API-Key: sk_live_YOUR_API_KEY"

Authentication Errors

401 Unauthorized

No API key provided or key is invalid.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

API key doesn't have the required scope.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key missing required scope: orders:write"
  }
}

Recommended Key Setup

Create separate API keys for different purposes:

PurposeRecommended Scopes
Public Storefrontproducts:read, categories:read, pages:read
Checkout Backendorders:write, customers:write, products:read
Admin IntegrationAll scopes (full access)
Product Import Scriptproducts:write, categories:write, media:write

Security Best Practices

  1. Never expose keys in frontend code — API keys should only be used server-side
  2. Use environment variables — Store keys in .env files, never commit them
  3. Use minimum required scopes — Principle of least privilege
  4. Rotate keys periodically — Create new keys and deactivate old ones
  5. Use separate keys per environment — Different keys for dev, staging, production
  6. Monitor API key usage — Check audit logs for unusual activity

Environment Variables Setup

# .env.local
# BareCommerce API
BARECOMMERCE_API_URL=https://api.barecommercecore.com
BARECOMMERCE_STORE_ID=store_xxxxxxxx
BARECOMMERCE_API_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
# Never commit this file to version control!

Reusable Client

// lib/barecommerce.ts
const API_URL = process.env.BARECOMMERCE_API_URL;
const STORE_ID = process.env.BARECOMMERCE_STORE_ID;
const API_KEY = process.env.BARECOMMERCE_API_KEY;
 
export async function fetchFromBareCommerce(
  endpoint: string,
  options: RequestInit = {}
) {
  const response = await fetch(`${API_URL}/stores/${STORE_ID}${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });
 
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || 'API request failed');
  }
 
  return response.json();
}
 
// Usage
const products = await fetchFromBareCommerce('/products');

Next Steps

Need Help?

IntroductionCreate Your First Store