Public API keys and the API gateway

What this is forCopy Anchor Link

All public StoreOS API access goes through the API gateway at https://api.storeos.dev. You authenticate with a public API key from the merchant console.

Create and revoke keys under Organization settings → API keys. The same page shows Recent API calls for traffic that used your keys.

Create a keyCopy Anchor Link

1. Open your store in the StoreOS console.
2. Go to Organization settings → API keys.
3. Choose Create key, give it a name, and pick scopes.
4. Copy the secret immediately — StoreOS shows the full key once.

The key looks like sos_live_…. After creation you only see a short prefix in the list (for example sos_live_a1b2c3d4…).

ScopesCopy Anchor Link

For each service, choose Off, Query (reads), Mutation (writes), or All.

Give each integration the least access it needs. Revoke a key from the same page if it is leaked or no longer used.

Call the gatewayCopy Anchor Link

Base URL:

https://api.storeos.dev

Browse without a key (Swagger UI, GraphQL Playground shell, and schema introspection). Try-it-out / data queries still need x-storeos-key:

HeadersCopy Anchor Link

The gateway sets the store (x-tenant) from the key. Do not put the API key in Authorization.

REST exampleCopy Anchor Link

curl "https://api.storeos.dev/storefront/api/v1/products?limit=12" \
  -H "x-storeos-key: sos_live_YOUR_KEY"

GraphQL exampleCopy Anchor Link

curl "https://api.storeos.dev/storefront/graphql" \
  -H "x-storeos-key: sos_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ products(input: { limit: 3 }) { nodes { title } } }"}'

TypeScript SDKCopy Anchor Link

import { StoreFront } from "@storeos/storefront-client";

const store = new StoreFront({
  tenant: "your-tenant-uid",
  apiKey: process.env.STOREOS_API_KEY!, // sos_live_…
  // baseUrl defaults to https://api.storeos.dev/storefront
});

const { nodes } = await store.getProducts({ limit: 12 });

→ SDK configuration

Recent API call logsCopy Anchor Link

On Organization settings → API keys, the Recent API calls table lists gateway requests that used your store’s keys (see the screenshot above).

Each row shows:

• When the call happened
• Which key (name + prefix)
• Method and path
• Upstream service and operation (query / mutation)
• HTTP status and duration

Logs refresh automatically and keep recent traffic (about two weeks). Use them to confirm an integration is hitting the gateway, to spot failed calls (4xx / 5xx), and to see which key was used.

Good practicesCopy Anchor Link

• Store keys in server env vars or a secrets manager — never in a public frontend bundle.
• Prefer storefront:query for read-only catalog bots; use :mutation or :all only when writes are required.
• Rotate by creating a new key, updating the integration, then revoking the old one.
• Keep customer JWTs in Authorization; keep the StoreOS key in x-storeos-key.

Related docsCopy Anchor Link