GraphQL API

Authentication, generated CRUD, and the named custom GraphQL operations in Openfront E-commerce.

Openfront serves GraphQL at /api/graphql (pages/api/graphql.ts, using GraphQL Yoga over the Keystone context). The schema is generated from features/keystone/models plus the custom operations registered in features/keystone/mutations/index.ts. The checked-in schema.graphql in the source repository is the reference for a given revision.

Authentication

Dashboard and storefront requests use the keystonejs-session cookie.
Authorization: Bearer of_... uses an API key. The key must be active, not expired, and allowed for the client IP if restrictedToIPs is set.
Authorization: Bearer <oauth access token> uses an OAuth app token. The app must be active.
Authorization: Bearer ctok_... uses a business customer token.
Authorization: Bearer mcp_at_... uses an MCP OAuth token. Without mcp:write, mutations are refused.
Guest carts send the signed proof from createActiveCart in the x-openfront-cart-proof header.

API-key and OAuth scopes add permissions on top of the owner's role. See Marketplace & OAuth.

Generated CRUD

Every list has the usual Keystone queries and mutations, for example products, product, productsCount, createProduct and updateProduct. Each list's access rules apply. Non-staff callers only see published products and active categories.

query PublishedProducts {
  products(where: { status: { equals: published } }, take: 10) {
    id
    title
    handle
    thumbnail
    productVariants {
      id
      title
      sku
      inventoryQuantity
    }
    productImages {
      image { url }
      imagePath
      altText
    }
    productCategories {
      title
      handle
    }
  }
}

curl https://your-openfront.example/api/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_KEY' \
  --data '{"query":"query { products(take: 1) { id title handle } }"}'

Custom queries

Query	Purpose
`redirectToInit`	True while there are no users
`activeCart(cartId)`	Cart for its owner or proof holder
`activeCartRegion(countryCode)`	Region for a country
`activeCartShippingOptions(cartId)`	Shipping options for a cart
`activeCartPaymentProviders(regionId)`	Installed and configured providers for a region
`getProductsSortedByPrice(countryCode, limit, offset, priceOrder, collectionId, categoryId)`	Product listing sorted by regional price
`getCustomerOrders(limit, offset)`, `getCustomerOrder(orderId, secretKey)`	Customer order history and detail
`getCustomerAccounts`, `getCustomerAccount(accountId)`	Business accounts of the signed-in user
`getUnpaidLineItemsByRegion(accountId)`	Unpaid account lines grouped by region
`activeInvoice(invoiceId)`, `getInvoicePaymentSessions(invoiceId)`, `getCustomerPaidInvoices`	Invoices
`getAnalytics(timeframe)`	Dashboard analytics
`getFinanceClose(start, end)`	Finance summary for a range up to 31 days (staff only)
`getMyPrivacyData`	The signed-in user's own data

Custom mutations

Area	Mutations
Customer	`updateActiveUser`, `updateActiveUserPassword`, `createActiveUserAddress`, `updateActiveUserAddress`, `deleteActiveUserAddress`, `updatePrivacyPreferences`, `requestPrivacyAction`
Cart	`createActiveCart`, `updateActiveCart`, `updateActiveCartLineItem`, `addDiscountToActiveCart`, `removeDiscountFromActiveCart`, `addActiveCartShippingMethod`
Payment	`createActiveCartPaymentSessions`, `initiatePaymentSession`, `setActiveCartPaymentSession`, `completeActiveCart`, `handlePaymentProviderWebhook`
Invoices	`createInvoiceFromLineItems`, `createInvoicePaymentSessions`, `initiateInvoicePaymentSession`, `setInvoicePaymentSession`, `completeInvoicePayment`, `regenerateCustomerToken`
Inventory	`adjustInventory`, `importInventory` (creates a batch job only)
Shipping	`getRatesForOrder`, `validateShippingAddress`, `trackShipment`, `createProviderShippingLabel`, `cancelShippingLabel`
Orders	`createOrderFulfillment`, `cancelOrderFulfillment`, `transitionOrderStatus`, `processReturnRefund`
Webhooks	`registerWebhookEndpoint`, `retryWebhookDeliveries`

Notes:

transitionOrderStatus only accepts canceled or archived, with a reason. Other order statuses change through payment and fulfillment.
createOrderFulfillment, createProviderShippingLabel and processReturnRefund require an idempotencyKey.
updateActiveCart ignores changes to user, order and payment links, and rejects gift cards and metadata.

Schema visualizer

The schema visualizer shows model relationships. The generated schema.graphql remains the authoritative API reference for a revision.