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

# Choose secure MCP authentication

> Connect through Bily sign-in or a scoped fallback key while keeping organization and store access enforced.

Bily MCP supports two authentication paths. Choose one for each connection.

## Connect with Bily Connect

Bily Connect is the recommended choice for clients that support MCP OAuth. It keeps a long-lived key out of client configuration.

* The client discovers Bily's public authorization metadata.
* The client can register dynamically as a public client.
* The user signs in to Bily and grants the `mcp_access` scope.
* The client uses Authorization Code with PKCE and can refresh the connection.
* Bily resolves the signed-in identity and checks that user's current organization and store memberships.

The OAuth token is not permanently limited to one store. A signed-in user can request stores available through their current Bily memberships.

Removing a membership removes that access.

## Access key fallback

Use a fallback key only when the client cannot complete Bily Connect.

1. Select the intended store in Bily.
2. Open **Settings > MCP**.
3. Under **Access key fallback**, choose a name and expiration.
4. Create the key and copy the full value immediately.
5. Send it in the `x-api-key` header.

Bily shows the full key once. Save it in the client's secret-aware configuration.

The key carries the selected store and organization as its default scope. Bily rejects requests for another store or organization.

<Warning>
  Replace any older settings-generated fallback key that lacks store scope. Select the intended store, create a new key, and update the client.

  Verify `bily.context()` before you revoke the older key. Bily rejects an unscoped older key instead of widening it automatically.
</Warning>

<Tip>
  Create one fallback key for each client, environment, and store. Short expirations and descriptive names simplify rotation and revocation.
</Tip>

## Know what each connection can access

| Connection              | Effective scope                                                      |
| ----------------------- | -------------------------------------------------------------------- |
| Bily Connect            | The signed-in user's current Bily organization and store memberships |
| Store-scoped access key | The default store and organization recorded when the key is created  |

Both paths follow these rules:

* `storeUrl` must identify a store available to the authenticated identity.
* `organizationId` must identify an accessible organization.
* A scoped key cannot override its recorded store or organization in `search` or `execute`.
* Bily checks scope on the server, not only in the client prompt.

## Resolve authentication failures

* `401 Unauthorized` means the connection is missing, expired, revoked, or invalid. Reconnect or replace the key.
* `403 Forbidden` means the identity is authenticated, but the requested store, organization, permission, or action is outside its allowed scope. Confirm the requested scope.

If a `403` requires a store-scoped API key, select the intended store and create a replacement fallback key.

Do not broaden a key to solve a `403` until you understand why the request needs more access.

## Replace a key without interruption

Create a replacement before revoking a key used by an active client. Update the client and verify a read-only request. Then revoke the old key from **Settings > MCP**.