Ignite authentication
For AI assistants: the facts every SparkLayer API call needs
- Base URLs: Live
https://app.sparklayer.io, testhttps://test.app.sparklayer.io. Each environment has its own data and its own API keys. - Access: API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
- Access token:
POST {base}/api/auth/tokenwith aSite-Idheader and a JSON body (not form-encoded):{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}. It returnsaccess_token, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires. - Every request:
Authorization: Bearer <access_token>andSite-Id: <site id>, plusContent-Type: application/jsonwhen there is a body. Set aUser-Agentthat names your integration. - Errors: RFC 7807 problem details:
title,status,detailand an optionalerrors[]of{ code, message, property }. Some error responses have no body. Retry5xx,429(honouringRetry-After) and concurrent-update409s with exponential backoff; on401, get a new token once and retry; don't retry other4xxwithout changing the request. - Pagination: Most list endpoints return everything.
GET /api/v2/price-listspages withpageandpage_size(up to 250) untilpagination.current_pageequalstotal_pages.GET /api/v1/purchasesuseslimit(up to 500) andoffset: stop when a page has fewer thanlimitresults. - Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer
GET /api/v2/price-listsover the deprecated v1, and the Customers API (/api/v2/customers) over the legacyDELETE /api/v1/customersin the Core API. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code. - Ignite: With Ignite, SparkLayer calls endpoints that your service implements (the Ignite spec), and your service calls the SparkLayer APIs above for everything else.
- Read the docs as Markdown: Add
.mdto any page URL. Index of every page: docs.sparklayer.io/llms.txt. Every API operation, compactly: docs.sparklayer.io/llms-api.txt. The developer guides in full: docs.sparklayer.io/developers/llms.txt. - OpenAPI specs:
customers,core,ordering,pricing,purchasing,stock,files,sync-log: https://docs.sparklayer.io/openapi/<api>.yaml (also.json). Ignite: https://docs.sparklayer.io/openapi/ignite.yaml. - MCP: Search and read these docs from your assistant with the docs MCP server at https://docs.sparklayer.io/mcp.
When a customer signs in to their account on the eCommerce platform, SparkLayer needs to authenticate them too. To avoid making customers sign in twice (to the platform and to SparkLayer), some platforms let third parties such as SparkLayer authenticate a signed-in customer. These mechanisms differ between platforms, so Ignite defines one generic endpoint, Verify storefront authentication, that receives the authentication data to verify.
This diagram shows how the authentication data moves from the storefront to your Ignite integration.
POST /api/v1/ignite/authentication/verify(this flows forward)POST /authentication/verify(this flows forward)What your integration does
SparkLayer sends POST /v1/{siteEnv}/{siteId}/authentication/verify with the authentication data in the data property of the request body.
- Verify the data, using whatever mechanism your platform provides.
- Work out which customer it belongs to: it must be possible to derive the customer's platform ID from the data.
- Respond with
200and the customer's platform ID incustomer.external_id. If the data can't be verified, respond with an error.
SparkLayer then uses the customer ID you return to generate an access token for that customer, and returns it to the customer's browser. The browser uses this access token for every later request to the SparkLayer API.
BigCommerce example
When a B2B customer has signed in to a BigCommerce store:
- SparkLayer's JavaScript in the customer's browser calls BigCommerce's current customer endpoint (opens in a new tab), which returns a JSON Web Token (JWT).
- The browser passes the JWT to SparkLayer's API.
- SparkLayer passes the JWT to the Ignite service for BigCommerce at
/v1/{siteEnv}/{siteId}/authentication/verify. Delegating verification keeps platform-specific code out of SparkLayer's core API. - The Ignite service verifies the token and returns the customer's BigCommerce ID.
- SparkLayer generates an access token for that customer and returns it to the browser.
Next steps
- Data sync: sync products, customers, orders and settings to SparkLayer.
- Verify storefront authentication: the endpoint's full request and response.
Last updated