API access & authentication

Generate an API token to call the app's filter, search, and settings data directly from your own code, for custom storefronts and integrations.

What this does

Generates a personal access token that lets your own code call the app’s filter, search, and settings data directly over HTTPS — useful for a custom/headless storefront, a server-side integration, or any tooling that needs live filter and product data outside of the app’s own storefront widget.

Generate a token

In the app, go to Settings > API access.
Click Create token.
Give it a Name (for your own reference — e.g. “Headless storefront”).
Choose which scopes it needs: read:catalog (filter and search data) and/or read:config (app settings).
Choose an expiration: 3 months, 9 months, 1 year (default), or never.
Click Create. The full token is shown once — copy it now, since you won’t be able to see it again after closing the dialog.

You can have up to 10 active tokens per store at a time.

[SCREENSHOT: Settings > API access — token table and Create token modal]

Authenticate a request

Send the token as a Bearer token in the Authorization header of every request:

Authorization: Bearer glb_sfs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

All endpoints are relative to your store’s base URL, shown on the API access page:

https://{your-app-server}/sfs/v1

You don’t need to (and can’t) pass a shop parameter yourself — the token already identifies which store the request is for.

Scopes

Each token is granted one or both scopes when it’s created:

Scope	Grants access to
`read:catalog`	`GET /filter`, `GET /search`
`read:config`	`GET /settings`

Calling an endpoint with a token that doesn’t have the required scope returns a 403.

Managing tokens

On the API access page, each token shows its name, prefix (the first few characters — the full secret is never shown again), scopes, expiration, last-used time, and status. Use Rotate to issue a new token with the same name/scopes/expiration while immediately invalidating the old one (useful if a token may have leaked), or Revoke to disable a token permanently.

Errors

Authentication and rate-limit errors use the same shape on every endpoint: {"success": false, "message": "..."}. An individual endpoint’s own business-logic errors (for example, an unrecognized form_id on GET /filter) may use a different shape — see that endpoint’s own Errors section.

Status	Cause
`401`	Missing `Authorization` header, or the token is invalid, revoked, or expired.
`403`	Token doesn’t have the required scope, or the store is currently unavailable.
`422`	Request parameters failed validation.
`429`	Too many requests — see Rate limits below.

Rate limits

Requests are throttled per store. If you exceed the limit, you’ll get a 429 response with Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining headers — back off and retry after the time indicated.

Was this helpful?

Report an issue