Storefront API keys

Public per-account keys. They identify the account, set CORS allowlist, and gate which operations a storefront client may invoke.

Format

pk_<env>_<32 random chars>

<env> is live or test. The dashboard shows only the last four characters after creation; the full key is returned exactly once in the create response.

Mint a key

curl -X POST "$API/storefront_keys.json" \
  -H "Authorization: Bearer $NEVIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production storefront",
    "env": "live",
    "allowed_origins": ["https://shop.example.com", "https://*.example.com"],
    "scopes": ["storefront:read","storefront:cart:write","storefront:checkout:write"],
    "rate_limit_per_minute": 600
  }'

Response:

{
  "storefront_key": {
    "id": "308...",
    "name": "Production storefront",
    "key": "pk_live_abcd...wxyz",
    "key_suffix": "wxyz",
    "allowed_origins": ["https://shop.example.com", "https://*.example.com"],
    "scopes": ["storefront:read","storefront:cart:write","storefront:checkout:write"],
    "status": "active",
    "rate_limit_per_minute": 600
  }
}

The key field is only ever returned in this create response — list and get responses redact it. Save it immediately.

List keys

curl "$API/storefront_keys.json" \
  -H "Authorization: Bearer $NEVIOS_KEY"

{
  "storefront_keys": [
    { "id": "308...", "name": "...", "key_suffix": "wxyz", "status": "active", ... }
  ]
}

Pass ?include_revoked=true to see revoked keys too.

Revoke a key

curl -X DELETE "$API/storefront_keys/{key_id}.json" \
  -H "Authorization: Bearer $NEVIOS_KEY"

Revocation is instantaneous — the next request with that key returns 401. Active carts and checkouts that were created with the key remain accessible (their token is the actual auth boundary).

Available scopes

Scope	Permits
storefront:read	GET on cart and checkout
storefront:cart:write	POST/PATCH/DELETE on cart and lines
storefront:checkout:write	POST/PATCH on checkout, address, shipping, discount, payment, complete

A key without the required scope returns 403 with a descriptive message including have_scopes and required_scope.

Origin allowlist

If allowed_origins is empty, any origin (or no origin) is accepted. Set the list to lock the key to your storefront domain(s):

{ "allowed_origins": ["https://shop.example.com", "https://*.example.com"] }

The check matches the Origin request header. Wildcards must be at the leftmost label (https://*.example.com matches https://store.example.com and https://www.example.com but not https://example.com).

Rotation strategy

Storefront keys appear in your JS bundle, so treat any rotation as a graceful migration:

1. Mint a new key alongside the existing one.
2. Deploy the storefront with the new key.
3. After a deploy verification window, revoke the old key.

Don't rotate during peak hours unless the old key is compromised.

Next: Carts API.