> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bily.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Keep API work in the right store

> Use Bily organization and store boundaries to keep every request within its intended customer scope.

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:

```http theme={null}
x-bily-organization-id: org_01J8W7T9G3E6ZQ4M2K5N8P1R0S
```

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.

```text theme={null}
GET /ad-metrics/store.example.com?startDate=2026-07-01&endDate=2026-07-07
```

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.

<Warning>
  Never forward a store URL from an untrusted client until your application confirms that it intended to access that store.
</Warning>

## 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.                          |

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:

```json theme={null}
{
  "organizationId": "org_01J8W7T9G3E6ZQ4M2K5N8P1R0S",
  "storeUrl": "store.example.com"
}
```

Run `GET /context` again after a membership or connection changes. Never copy identifiers between customer accounts.