# Bring your own AI key

Your storefront assistant, product and review summaries, and AI search all call OpenAI.
By default those calls use the AI included in your Mercemur plan. Connect your own
OpenAI key and they are charged to your OpenAI account instead.

This changes **who pays the AI provider**, and nothing else. Your Mercemur subscription
is the same either way, and your AI features work the same way before and after.

## Connect a key

1. Create an API key in your OpenAI dashboard, under **API keys**.
2. In Mercemur, go to **Settings > AI provider key**.
3. Paste the key and save.

We check the key against OpenAI **before** storing anything, so a key that is refused
leaves nothing behind. You never see a connected key that was not actually accepted.

<Info>
  A restricted key is enough, and is what we recommend. It needs write access to model
  capabilities, and nothing else. It does not need permission to list models, read your
  usage, or manage your account.
</Info>

## What a restricted key needs

The check embeds a single token with `text-embedding-3-small`, which is the same model
and the same permission your store's real calls use. That is deliberate: a key that
passes the check is a key that can do the work, rather than one that merely exists.

If your key is valid but too narrow, you are told to **widen the key you have** rather
than to replace it. Those are different fixes and the screen keeps them apart.

## The model does not change

Your key pays for the calls. It does not choose the model.

Embeddings are pinned to one model platform-side because every store's vectors share a
single collection at a fixed size. A merchant-chosen embedding model would either be
refused on write or would land vectors that do not sit correctly beside everyone else's.
Connecting or disconnecting a key therefore never invalidates what your store has
already learned, and nothing needs re-indexing either way.

## If your key stops working

A key can stop working after it was proven good: it gets revoked, the project loses
access to the model, or the account runs out of credit.

When that happens your store's AI features **pause**. They do not quietly fall back to
the AI in your plan.

<Warning>
  The fallback is deliberately absent. If a broken key silently moved your traffic back
  onto our key, you would keep being billed by us for usage you believed you were paying
  for yourself, and you would not find out until an invoice arrived.
</Warning>

The settings page separates two states that look alike and need different responses:

| State | What it means | What to do |
| --- | --- | --- |
| Not working | The key passed a check before and has stopped | Check the key's OpenAI project for revocation, model access, or credit |
| Never worked | The key has never passed a check | Paste it again, or disconnect to go back to the included AI |

Use **Check key** on the settings page to re-run the check against OpenAI at any time,
so you find out there rather than from an assistant that has gone quiet.

## Disconnect

Disconnecting puts you straight back on the AI included in your plan. Your AI features
keep working; OpenAI simply stops charging your account for them.

## Things worth knowing

- **The key is never shown again.** After you save it, the settings page shows only the
  last four characters, so you can tell which of your keys is connected.
- **Every change is recorded.** Saving, checking, and disconnecting a key each write an
  audit entry naming who did it. The entries never contain the key itself.
- **This screen is rate limited** to 20 requests a minute per store.
- **OpenAI is the only provider today.** The storage and the settings screen were built
  to take more than one, so adding another does not change what you have set up here.