# Ignite authentication

URL: https://docs.sparklayer.io/ignite/authentication

How Ignite verifies platform customer sessions: SparkLayer passes a token such as a BigCommerce JWT to /authentication/verify and issues an access token.

> **For AI assistants:** these facts apply to every SparkLayer API call.
>
> - **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 `409`s 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: https://docs.sparklayer.io/llms.txt. Every API operation, compactly: https://docs.sparklayer.io/llms-api.txt. The developer guides in full: https://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](https://docs.sparklayer.io/ignite/api/verify-authentication.md), 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:

1. Front end → SparkLayer API: `POST /api/v1/ignite/authentication/verify`
2. SparkLayer API → Ignite API: `POST /authentication/verify`
3. The Ignite API verifies the authentication data.
4. Ignite API → SparkLayer API: the customer ID.
5. The SparkLayer API generates an access token for that customer ID.
6. SparkLayer API → front end: the access token.

## 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](https://developer.bigcommerce.com/docs/storefront-auth/current-customer#get-current-customer), 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

- [Data sync](https://docs.sparklayer.io/ignite/data-sync.md): sync products, customers, orders and settings to SparkLayer.
- [Verify storefront authentication](https://docs.sparklayer.io/ignite/api/verify-authentication.md): the endpoint's full request and response.
