Store apps
Hosted Shopify, Salla and Zid apps: OAuth install, webhooks, embedded admin.
5 endpoints.
GET /v1/connectors/{platform}/installGET /v1/connectors/{platform}/oauth/callbackPOST /v1/connectors/{platform}/webhooksPOST /v1/connectors/{platform}/sessionGET /v1/connectors/{platform}/storefront
/v1/connectors/{platform}/installStart the app install: redirect to the platform's OAuth consent page
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
platform | path | "shopify" | "salla" | "zid" | yes | |
shop | query | string | null | no | Shopify: <name>.myshopify.com · max length 255 |
Responses
- 302Redirect to the platform (install) or to the embedded admin (callback)
/v1/connectors/{platform}/oauth/callbackOAuth callback: check state + signature, store tokens, create or link the tenant
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
platform | path | "shopify" | "salla" | "zid" | yes |
Responses
- 302Redirect to the platform (install) or to the embedded admin (callback)
/v1/connectors/{platform}/webhooksPlatform webhooks: products, app uninstalled, Shopify GDPR topics (signature checked)
Shopify sends the topic in `X-Shopify-Topic`: products/create|update|delete, app/uninstalled, customers/data_request, customers/redact, shop/redact (mandatory GDPR webhooks). SeekGist stores no shopper personal data, so the customer topics are answered 200 and logged; shop/redact deletes the tenant's data (same job as POST /v1/data/requests kind=delete). Answer within 5 s; do the work in a job.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
platform | path | "shopify" | "salla" | "zid" | yes |
Responses
- 200Successful Response
WebhookAck
/v1/connectors/{platform}/sessionEmbedded admin: exchange the platform session token for a SeekGist session
Sets the `sg_session` cookie (SameSite=None; Secure, because the admin runs inside the platform's iframe) for the store's tenant, with role owner, valid 1 hour. CSRF works as for the dashboard.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
platform | path | "shopify" | "salla" | "zid" | yes |
Request body application/json StoreAppSessionRequest
| Name | Type | Required | Description |
|---|---|---|---|
token | string | yes | Shopify: App Bridge session token (JWT, HS256, signed with the app secret). Salla / Zid: the token their embedded page gives the app.min length 20 · max length 4000 |
Responses
- 200Successful Response
LoginResult
/v1/connectors/{platform}/storefrontStorefront script config: the shop's public key and on/off switch
Called by the store-app storefront script (theme app extension / app snippet) before it starts the widget. Returns only public data: the public key is meant for browsers and is locked to the shop's origins. Unknown or switched-off shops get `enabled: false`. Cached (`Cache-Control: public, max-age=30`).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
platform | path | "shopify" | "salla" | "zid" | yes | |
shop | query | string | yes | Shopify: <name>.myshopify.com; Salla / Zid: store id · min length 1 · max length 255 |
Responses
- 200Successful Response
StorefrontConfig
Data shapes on this page
WebhookAck
| Name | Type | Required | Description |
|---|---|---|---|
ok | boolean | no | default true |
StoreAppSessionRequest
Embedded admin: trade the platform's short-lived session token for a SeekGist dashboard session.
| Name | Type | Required | Description |
|---|---|---|---|
token | string | yes | Shopify: App Bridge session token (JWT, HS256, signed with the app secret). Salla / Zid: the token their embedded page gives the app.min length 20 · max length 4000 |
LoginResult
On success the API sets the `sg_session` cookie (HttpOnly, Secure, SameSite=Lax) and returns the CSRF token, which the web app sends back as `X-CSRF-Token` on every write.
| Name | Type | Required | Description |
|---|---|---|---|
status | "ok" | "mfa_required" | "email_sent" | yes | |
user | UserOut | null | no | |
csrf_token | string | null | no | |
weak_password | boolean | no | Password sign-in only: the password is on the breached-password list or no longer meets the rules. Sign-in still works; ask the user to change it (POST /v1/auth/password/change).default false |
UserOut
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
email | string | yes | |
name | string | null | yes | |
locale | "en" | "ar" | yes | |
email_verified | boolean | yes | |
totp_enabled | boolean | yes | |
is_superadmin | boolean | yes | |
memberships | MembershipOut[] | yes |
MembershipOut
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
tenant_id | string | yes | |
tenant_name | string | yes | |
tenant_slug | string | yes | |
role | "owner" | "admin" | "editor" | "viewer" | yes |
StorefrontConfig
What the store-app storefront script needs to start the widget. `enabled: false` (unknown shop, app uninstalled or switched off in the embedded admin) means: leave the store's own search alone.
| Name | Type | Required | Description |
|---|---|---|---|
enabled | boolean | yes | |
key | string | null | no | The store's public key (sg_pub_...), safe in a browser. |
locale | string | no | default "en" |
suggest | boolean | no | default true |
search | boolean | no | default true |
assistant | boolean | no | default false |