# Authentication

The Storefront GraphQL API requires authentication using an API key. All requests must include a valid API key in the
`Authorization` header to access the GraphQL API.

## API Key Types

There are two types of API keys available for the Storefront API:

### Public Keys (`fq_public`)

Public API keys provide access to basic endpoints and resources. They can be used for:

- Fetching products
- Modifying shopping carts
- Basic storefront operations

Public keys are suitable for client-side applications where the key may be exposed, as they have limited permissions.

### Secret Keys (`fq_secret`)

Secret API keys are server-side keys that require specific scopes to access protected resources. They provide access to:

- All basic endpoints (same as public keys)
- Additional resources that require scopes (see below)

Secret keys should **never** be exposed in client-side code or public repositories. They must be kept secure on your
server.

## Available Scopes

Secret keys can be configured with the following scopes to access specific resources:

### Permissions

- `navigation:read` - Read store navigation and menus

### MCP Tools

- `search_products` - Search products from the store
- `get_product` - Fetch detailed product information
- `create_cart` - Create new shopping cart
- `get_cart` - Fetch shopping cart information
- `add_cart_lines` - Add items to shopping cart
- `update_cart_lines` - Update shopping cart item quantities
- `remove_cart_lines` - Remove items from shopping cart

When creating a secret key in the Finqu admin area, you can select which scopes the key should have access to.

## Obtaining Your API Key

API keys can be obtained from the Channel settings in the Finqu admin area. Keys are prefixed with `fq_` and look like
`fq_OPmgGrIY...` (for public keys) or `fq_secret_...` (for secret keys).

## How to Access the API

Include your API key in the `Authorization` header when making requests to the Storefront API endpoint.

Example request:

```http
POST https://<your-store-domain>/graphql/<version> HTTP/1.1
Content-Type: application/json
Authorization: fq_public_OPmgGrIY...

{
  "query": "{ products { id title } }"
}
```

## Security Best Practices

- **Keep your API key secure** - Never expose your API key in client-side code or public repositories
- **Use public keys for client-side** - Use `fq_public` keys for client-side applications where the key may be exposed
- **Use secret keys for server-side only** - Use `fq_secret` keys only in secure server environments
- **Use environment variables** - Store your API key in environment variables or secure configuration
- **Rotate keys regularly** - If you suspect a key has been compromised, generate a new one from the Channel settings
- **Grant minimal scopes** - When creating secret keys, only grant the scopes that are necessary for your use case

If you have questions or need support, please contact our support team.