Skip to main content

Claim Install (Attach to Existing Workspace)

POST 
//:domain/api/shopify/install/:claimToken/claim

AUTHENTICATED. Attaches a stashed cold install to a workspace the signed-in merchant already belongs to. The merchant MUST already have a SKU.io account — this flow never creates users or tenants.

The bearer user is resolved from auth:sanctum manually (no route middleware), so the claim page stays anonymous until the merchant signs in; a Bearer token is therefore REQUIRED and an anonymous request is rejected with 401.

Resolves synchronously and returns 200 with the cross-subdomain tenant-switch handoff, which the claim page uses to drop the merchant onto their tenant, authenticated. A re-install into a tenant that already has an instance for the shop refreshes that instance's token in place (no duplicate).

Throttled to 30 req/min.

Request fields:

  • tenant_id (string, required): the id of a workspace the signed-in merchant already belongs to; validated against the central tenants table.

Responses:

  • 200 OK: handoff payload — status=claimed, switch_token, target_host, tenant_id, instance_id, landing_path.
  • 401 Unauthorized: no signed-in user (the merchant must sign in first).
  • 404 Not Found: unknown/consumed claim token.
  • 409 Conflict: the store is already being connected (lost the atomic claim race) or already claimed.
  • 410 Gone: the claim link has expired (reinstall from the App Store).
  • 422 Unprocessable: validation error (e.g. unknown tenant_id).

Request​

Responses​

OK

Response Headers
    Content-Type