Skip to main content

Start Store Connection

GET 
/api/storefront/connect/init

Begin connecting a store. The store's owner approves the connection on the store itself and the store issues a per-connection API key — no key is ever typed into SKU.io on this path.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

What happens: the settings below are validated, the store address is probed, the settings are parked under a one-time state for 15 minutes, and the store's approval URL is returned as data.authorization_url. Send the browser there. When the owner approves, the store redirects back to GET /storefront/oauth/callback on the tenant's own host with a one-time code, which SKU.io exchanges server to server for the API key. The instance is created in that callback, not here — a successful call to this endpoint creates nothing.

The store address is probed before the redirect (new behaviour). The address is typed by a human, so a typo used to hand the browser to a stranger's site and surface as an unexplained 404 away from SKU.io. The probe calls the Store API GET /health without a key: a live store answers 401 (the API is there and wants a key), which passes. Failure modes:

  • 404 or 410 — something answers at that address but it is not a store. 422, with the reason on the store_url field: We could not find a store at <url>. Check the address and try again.
  • A host that cannot be a store — a single-label host such as https://intranet is rejected without spending a request, because anything that answers would read as "the store exists". Same 422.
  • Everything else fails OPEN — a timeout, a DNS or TLS failure, a 5xx, or an HTML error page from a proxy all allow the connect to proceed. The probe is a guard, not a dependency: an unwell store must never block a merchant connecting a real one.
  • Reconnect is never probed. With integration_instance_id set, the address is one SKU.io has already been talking to, and re-keying is exactly what you do when a store is misbehaving.

Other failures: 422 That integration is not a Storefront. when integration_instance_id points at another kind of integration; 422 field errors for a name already in use, an address that is not a bare origin, or a start date before the tenant's inventory start date.

The name is re-checked in the callback as well — minutes pass on the store's approval screen, and a name claimed in the meantime is reported there with a free alternative rather than as a database error.

Permission: integrations.update.

Authentication: Bearer token (session or PAT).

Request​

Responses​

OK

Response Headers
    Content-Type