Skip to main content
Bily protects customer access with two boundaries: organizations and stores. An organization is the team that owns access. A store is one connected commerce or web property inside that organization.

​
Give each key one store

An API key created under Settings > MCP > Access key fallback carries the selected store and its organization. Bily limits discovery responses to that scope and rejects requests for another store or organization. Create a separate key when a workload needs another store. Never reuse one customer key as a multi-store credential. Bily rejects an older settings-generated fallback key that lacks organization and store scope. Select the intended store and regenerate the key before using the customer API or MCP.

​
Confirm the available scope

Call GET /context without an organization parameter when you use a standard store-scoped key. Bily returns the authenticated user and a scoped organizations array. Each visible store appears under its organization. Use the optional organizationId query only when an identity can access multiple organizations and the request deliberately selects one. The organization must remain inside the credential’s allowed scope.

​
Make an organization-scoped request

GET /stores requires the organization header:
Get valid organization IDs from GET /context or GET /organizations. Bily confirms that the authenticated identity belongs to the supplied organization.

​
Make a store-scoped request

Store-scoped paths include {storeUrl}. Copy the exact url from GET /context or GET /stores. Encode it as a URL path segment when necessary.
Bily derives the organization from the store and verifies access. You can also send x-bily-organization-id. Its value must match the store’s organization.
Never forward a store URL from an untrusted client until your application confirms that it intended to access that store.

​
Resolve scope errors

To protect privacy, Bily may return 404 instead of revealing that a store exists under another organization.

​
Store scope with every job

For scheduled and multi-tenant jobs, store these values together:
Run GET /context again after a membership or connection changes. Never copy identifiers between customer accounts.