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:
x-bily-organization-id: org_01J8W7T9G3E6ZQ4M2K5N8P1R0S
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.
GET /ad-metrics/store.example.com?startDate=2026-07-01&endDate=2026-07-07
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
| Status | Meaning |
|---|
400 | A required organization header or store URL is missing or malformed. |
403 | The identity cannot access the supplied organization or an explicitly scoped store. |
404 | The store does not exist in the caller’s accessible scope. |
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:
{
"organizationId": "org_01J8W7T9G3E6ZQ4M2K5N8P1R0S",
"storeUrl": "store.example.com"
}
GET /context again after a membership or connection changes. Never copy identifiers between customer accounts. 
