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

# Authenticate API requests

> Give trusted services scoped Bily access while keeping API keys out of public code, logs, and repositories.

Use a Bily API key to give trusted server workloads scoped access. Keep the key out of browser JavaScript, mobile application code, public repositories, and client-visible environment variables.

## Create a scoped key

1. Sign in to [Bily](https://app.bily.ai).
2. Select the store this workload may access.
3. Open **Settings**.
4. Open **MCP**.
5. Under **Access key fallback**, enter a descriptive name and expiration.
6. Create the key and copy its full value immediately.

Bily shows the full key once. Save it in your deployment platform's secret manager.

The key uses the selected store and its organization as its default API scope.

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

  Revoke the older key after the replacement passes a read-only `GET /context` check.
</Warning>

<Tip>
  Create one key for each environment and workload. Names such as `reporting-production` and `catalog-sync-staging` simplify rotation and audit review.
</Tip>

## Add the key to requests

Send the key in the recommended `x-api-key` header:

```bash theme={null}
curl --request GET \
  --url https://app.bily.ai/api/customer/v1/context \
  --header "x-api-key: $BILY_API_KEY"
```

You can also use Bearer authentication:

```http theme={null}
Authorization: Bearer <BILY_API_KEY>
```

Choose one authentication method for each request.

## Keep keys protected

* Keep each key in server-side secret storage.
* Do not log request headers that may contain a key.
* Match the expiration to the workload's lifecycle.
* Create a replacement before revoking a production key.
* Revoke a key immediately if it may have been exposed.

## Fix authentication and permission errors

Each key includes the permissions available through the stable customer API. It also carries the selected store and organization scope.

Bily rejects requests for another store or organization. An action can also return `403` when the caller lacks its required permission.

A `401` means the key is missing, expired, revoked, or invalid. Replace or rotate it.

A `403` means the request is authenticated but cannot access the requested operation or scope. If the error requires a store-scoped key, select the intended store and create a replacement.

<Card title="Make your first request" icon="arrow-right" href="/rest-api/quickstart">
  Confirm the authenticated user, organization, and store in one request.
</Card>