API Reference
Scopes

API Key Scopes Reference

API key scopes control what operations your API key can perform. Use minimal scopes for security.

Scope Format

Scopes follow the format: {resource}.{capability}

Example: product.read, order.write

All Available Scopes

Products

  • product.read — List and view products
  • product.write — Create and update products
  • product.delete — Delete products

Orders

  • order.read — View orders (read-only in v1.7)

Note: order.write and order.delete scopes are deprecated as orders are now created exclusively via payment provider webhooks.

Customers

  • customer.read — List and view customers
  • customer.write — Create and update customers
  • customer.delete — Delete customers

Categories

  • category.read — View categories
  • category.write — Create and update categories
  • category.delete — Delete categories

Pages

  • page.read — View pages
  • page.write — Create and update pages
  • page.delete — Delete pages

Media

  • media.read — List and view media files
  • media.write — Upload media
  • media.delete — Delete media files

Webhooks

  • webhook.read — View webhook subscriptions
  • webhook.write — Create and update webhook subscriptions
  • webhook.delete — Delete webhook subscriptions

API Keys

  • apiKey.read — View API keys (shows prefix only, never full key)
  • apiKey.write — Create API keys
  • apiKey.delete — Revoke API keys

Audit Logs

  • auditLog.read — View audit log entries

Recommended Scope Combinations

Public Storefront

For a headless storefront fetching products and creating orders:

product.read
category.read
customer.write

Why:

  • product.read - Display products
  • category.read - Show categories
  • customer.write - Create customers from signup

Inventory Sync

For syncing products from an external system:

product.read
product.write
media.write

Why:

  • product.read - Fetch existing products
  • product.write - Create/update products
  • media.write - Upload product images

Order Fulfillment

For reading orders to ship:

order.read
customer.read

Why:

  • order.read - View orders to fulfill
  • customer.read - Get customer details for shipping label

Analytics Integration

For syncing data to analytics:

order.read
product.read
customer.read

Why:

  • order.read - Fetch orders
  • product.read - Fetch products
  • customer.read - Fetch customers

Full Store Management

For a management dashboard with all operations:

product.read
product.write
product.delete
order.read
customer.read
customer.write
customer.delete
category.read
category.write
category.delete
page.read
page.write
page.delete
media.read
media.write
media.delete
webhook.read
webhook.write
webhook.delete
auditLog.read
apiKey.read

Creating an API Key with Scopes

Via Dashboard

  1. Go to Settings → API Keys
  2. Click Create New Key
  3. Enter a name (e.g., "Inventory Sync")
  4. Check the scopes you need
  5. Click Create
  6. Copy the full key (shown only once)

Principle of Least Privilege

Always use the minimum scopes needed:

❌ WRONG - Over-permissive
apiKey with: product.*, order.*, customer.*, webhook.*, ...

✅ CORRECT - Minimal scopes
apiKey with: product.read, category.read

✅ CORRECT - Specific to use case
apiKey for inventory sync: product.read, product.write, media.write
apiKey for storefront: product.read, customer.write
apiKey for order fulfillment: order.read, customer.read

Checking Key Permissions

API keys are stored as hashes, so you can never see the full key again. To manage keys:

  1. Go to Settings → API Keys
  2. You'll see the prefix (first 12 chars) and creation date
  3. Click to see:
    • Scope list
    • Last used date
    • Creation date

Revoking Keys

To revoke a key immediately:

  1. Go to Settings → API Keys
  2. Find the key (by prefix)
  3. Click Delete
  4. The key is revoked instantly (no requests will work)

Note: This is permanent. The revoked key cannot be recovered.

Rotating Keys

Best practice: Rotate API keys periodically.

1. Create new key with same scopes as old key
2. Update your app to use new key
3. Test that everything works
4. Revoke old key
5. Monitor logs for any failures

Key Security Tips

✅ DO:

  • Store keys in environment variables (.env, secrets manager)
  • Use minimal scopes for each key
  • Rotate keys every 90 days
  • Create separate keys for different integrations
  • Monitor "Last Used" dates for unused keys
  • Revoke keys immediately if compromised

❌ DON'T:

  • Commit keys to Git
  • Share keys in Slack/email
  • Use one key for everything
  • Store keys in client-side code
  • Use placeholder/demo keys in production

Using Scopes in Requests

When you make API requests with your key, scopes are automatically checked:

# This works if your key has product.read
curl https://api.barecommercecore.com/api/stores/{storeId}/products \
  -H "X-API-Key: sk_live_your_key"
 
# This fails if your key doesn't have product.write
curl -X POST https://api.barecommercecore.com/api/stores/{storeId}/products \
  -H "X-API-Key: sk_live_your_key" \
  -d '{"title": "New Product", ...}'
# Error: FORBIDDEN - Insufficient permissions

Error: "FORBIDDEN - Insufficient permissions"

If you get this error:

  1. Check which scope the endpoint needs (see endpoint documentation)
  2. Get your API key prefix (first 12 chars of your key)
  3. Go to Settings → API Keys
  4. Click your key to view its scopes
  5. Either:
    • Add the missing scope (edit key), OR
    • Create a new key with the required scope

Next Steps

EventsQuick Start