Skip to content

Ignite authentication

For AI assistants: the facts every SparkLayer API call needs
  • Base URLs: Live https://app.sparklayer.io, test https://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/token with a Site-Id header and a JSON body (not form-encoded): {"grant_type":"client_credentials","client_id":"…","client_secret":"…"}. It returns access_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> and Site-Id: <site id>, plus Content-Type: application/json when there is a body. Set a User-Agent that names your integration.
  • Errors: RFC 7807 problem details: title, status, detail and an optional errors[] of { code, message, property }. Some error responses have no body. Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409s with exponential backoff; on 401, get a new token once and retry; don't retry other 4xx without changing the request.
  • Pagination: Most list endpoints return everything. GET /api/v2/price-lists pages with page and page_size (up to 250) until pagination.current_page equals total_pages. GET /api/v1/purchases uses limit (up to 500) and offset: stop when a page has fewer than limit results.
  • Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer GET /api/v2/price-lists over the deprecated v1, and the Customers API (/api/v2/customers) over the legacy DELETE /api/v1/customers in 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 .md to 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.

Ignite authentication sequence: the front end posts the customer's authentication data to the SparkLayer API, which forwards it to the Ignite API to verify; the Ignite API returns the customer ID and SparkLayer returns an access token to the front end.
Front end
SparkLayer API
Ignite API
POST /api/v1/ignite/authentication/verify(this flows forward)
POST /authentication/verify(this flows forward)
Verify authentication data
Customer ID(this flows back)
Generate an access token for the customer ID
Access token(this flows back)

What your integration does

SparkLayer sends POST /v1/{siteEnv}/{siteId}/authentication/verify with the authentication data in the data property of the request body.

  1. Verify the data, using whatever mechanism your platform provides.
  2. Work out which customer it belongs to: it must be possible to derive the customer's platform ID from the data.
  3. Respond with 200 and the customer's platform ID in customer.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:

  1. 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).
  2. The browser passes the JWT to SparkLayer's API.
  3. 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.
  4. The Ignite service verifies the token and returns the customer's BigCommerce ID.
  5. SparkLayer generates an access token for that customer and returns it to the browser.

Next steps

Was this page helpful?

Last updated