# Platform connection

URL: https://docs.sparklayer.io/ignite/platform-connection

Handle new and removed Ignite platform connections, whether started from a platform app store or the SparkLayer Dashboard, including redirect_url and full sync.

> **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.

A **platform connection** links an eCommerce platform store to a SparkLayer site. SparkLayer calls **two endpoints** on your integration: one when a platform is connected, and one when it's removed. A new connection can start from the eCommerce platform or from the SparkLayer Dashboard, and your integration needs to support both flows.

## Platform connection flows

### Initiated through the eCommerce platform

The merchant starts the connection from the platform's app store (or similar), for example by installing the SparkLayer app on BigCommerce or Shopify. This flow only applies if your platform supports third-party apps.

This flow uses the **SparkLayer Dashboard API** to register the user with SparkLayer, create a platform connection between the platform and a SparkLayer site, and get the site's onboarding progress. Its documentation isn't public, but we can provide it on request.

1. The merchant installs the SparkLayer app on their store.
2. Your integration stores the store's credentials and other data it needs, usually the store identifier and the platform's API access token or credentials.
3. The SparkLayer app on the platform shows the user a SparkLayer registration page. To register the user, call the Dashboard API's user registration endpoint.
4. When registration succeeds, SparkLayer returns the site environment and Site ID. Use them to call the Dashboard API's site platform connection endpoint, which links the store to the new SparkLayer site.
5. SparkLayer calls your integration's [Connect a platform](https://docs.sparklayer.io/ignite/api/new-platform-connection.md) endpoint with the Site ID and credentials. Store them and run the connection completion actions, such as a full data sync.
6. The connection is complete. In the platform's SparkLayer app, show the user the SparkLayer onboarding steps, with links to the SparkLayer Dashboard and the Help Center. Get the onboarding progress from the Dashboard API's onboarding steps endpoint.

### Initiated through the SparkLayer Dashboard

The merchant starts the connection from the eCommerce platform page of an existing SparkLayer site in the SparkLayer Dashboard (**Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app). 

1. SparkLayer calls your integration's [Connect a platform](https://docs.sparklayer.io/ignite/api/new-platform-connection.md) endpoint with the SparkLayer site and credentials.
2. Your integration stores this data and returns a `redirect_url`, where the merchant installs the SparkLayer app on the platform.
3. Once the app is installed, your integration stores the store's credentials and other data it needs.
4. Your integration now has both the SparkLayer and the platform data, so the connection is complete and it can start actions such as a full data sync.
5. Show the user the SparkLayer onboarding steps and progress, from the Dashboard API's onboarding steps endpoint.

## Platform connection endpoints

SparkLayer calls these endpoints to tell your integration about a new or removed platform connection.

### New platform connection

[Connect a platform](https://docs.sparklayer.io/ignite/api/new-platform-connection.md) (`POST /v1/{siteEnv}/{siteId}`) records the new connection, and runs the completion actions if the connection is complete.

The request body includes:

| Field | Description |
| --- | --- |
| `store_id` | The store's ID on the platform |
| `spark_api_client_id` and `spark_api_client_secret` | API credentials your integration uses to call the [SparkLayer API](https://docs.sparklayer.io/developers/api.md) for this site |
| `extra_config`, `magento_*` | Platform-specific credentials for WooCommerce and Magento |

Respond with:

- `201` and a `redirect_url` when the connection is pending: the SparkLayer Dashboard redirects the merchant there to install the SparkLayer app on the platform
- `204` when the app is already installed and the connection is now active

Once the connection is complete (your integration has the SparkLayer and platform configuration and credentials, and can start syncing data):

1. Register any data change webhooks with the platform, if it has them.
2. Sync the store settings from the platform to the SparkLayer API.
3. Start a full sync of customers and products.

**Important considerations:**

- The connection may not be complete when SparkLayer calls this endpoint: for example, when the connection starts in the SparkLayer Dashboard and the merchant still has to finish it on the platform. In that case, return a `redirect_url` to the platform's SparkLayer installation page, where the merchant links their store to the pending connection.
- The endpoint must be idempotent, because SparkLayer may call it more than once. If the connection is already established, re-trigger the completion actions safely.

### Remove platform connection

[Disconnect a platform](https://docs.sparklayer.io/ignite/api/remove-platform-connection.md) (`DELETE /v1/{siteEnv}/{siteId}`) should:

- Stop processing any syncs
- [Delete the store's sync logs](https://docs.sparklayer.io/developers/api/sync-log/delete-a-stores-sync-logs.md)
- Delete the connection data stored by your integration

## Authentication between SparkLayer and your integration

**Calls from your integration to SparkLayer.** Use the `spark_api_client_id` and `spark_api_client_secret` from the connect request to get OAuth access tokens, as described in [Authentication](https://docs.sparklayer.io/developers/authentication.md). Tokens are short-lived, so store them with the connection data and refresh them when they expire.

**Calls from SparkLayer to your integration.** The Ignite spec lists `401 Auth Failure` responses for these endpoints, but doesn't define how SparkLayer authenticates its requests. 

## Next steps

- [Authentication](https://docs.sparklayer.io/ignite/authentication.md): verify customers signed in to your platform.
- [Data sync](https://docs.sparklayer.io/ignite/data-sync.md): the full sync to run once the connection is complete.
