Authentication

Authenticate Storefront API requests with your storefront API key.

Storefront API key

Pass your storefront API key in the Authorization header.

curl -X POST https://api.colossal.sh/api/v1/graphql \
  -H "Authorization: Bearer YOUR_STOREFRONT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ storeDetailsByUid(uid: \"your-store-uid\") { name } }"}'

Getting your API key

1. Log in to the Colossal dashboard
2. Navigate to Settings > API Keys
3. Copy your storefront API key

Storefront API keys are safe to use in client-side code. They provide read access to products and store configuration, and write access to carts and checkout sessions.

Using with the SDK

The Storefront SDK handles authentication automatically:

import { initStorefrontClient } from "@colossal-sh/storefront-sdk";

initStorefrontClient({
  storeUid: process.env.COLOSSAL_STORE_UID,
  apiKey: process.env.COLOSSAL_STOREFRONT_API_KEY,
});

Error responses

Invalid or missing authentication returns:

{
  "errors": [
    {
      "message": "Authentication required",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}