Authentication

API v2 takes the same API keys as API v1: expiring keys you create in Filemonk, several per store if you like. There are two ways in: the API key for your own code, and OAuth for AI assistants that connect to the MCP server.

Creating an API key

1. Open Filemonk settings

   In your Shopify admin, open the Filemonk app and go to Settings.

2. Go to the Other tab

   Select the Other tab and scroll to the API section.

3. Create a key and copy it

   Click Create API key, name it, and choose when it expires (30 days, 90 days, 1 year, or no expiry). Copy the key from the banner: it is shown only once.

A key with an expiry date stops working on that date; the store owner is emailed 14 and 3 days before. A No expiry key works until it is revoked. Rotate issues a replacement and keeps the old key working for 7 days. Expiry, rotation, revocation and the legacy key are described in Authentication.

Caution

Treat the API key like a password. It can read and change everything in your Filemonk account, including sending emails to your buyers. Never put it in front-end code, a public repository, or a chat with an AI assistant.

Sending the key

Send it in the X-Auth-Token header on every request:

curl 'https://app.filemonk.io/api/v2/external/account' \
  -H 'X-Auth-Token: fm_api_key_your_key_here'

X-API-Key: <key> and Authorization: Bearer <key> are accepted as well, so a tool that only knows how to send a bearer token works without changes.

A missing, wrong, expired or revoked key is a 401 whose code says which (missing_api_key, invalid_api_key, expired_api_key, revoked_api_key, retired_api_key):

{
  "errors": ["API key is required"],
  "code": "missing_api_key",
  "retryable": false
}

A request made with the store’s legacy key (fm_api_key_…, no expiry) still works for now, with Deprecation and, once announced, Sunset headers; its error responses also carry a warnings array.

Each key belongs to one store, and every request only ever sees that store’s data. Keep it out of anything you share.

Public documents

You do not need a key to read the documentation the app serves: the OpenAPI document, skill.md and llms.txt are public. See For AI agents.

AI assistants: OAuth and the connector key

AI assistants such as Claude and ChatGPT should not be given your API key. They connect to the MCP server at https://app.filemonk.io/api/v2/external/mcp and sign in with OAuth instead:

1. The assistant registers itself and opens a Filemonk sign-in page.
2. You enter your store’s myshopify.com address and approve the connection in your Shopify admin. The page shows who is asking and what they will be able to do.
3. The assistant receives a token that lasts 24 hours and refreshes itself for up to 90 days of use.

If you cannot approve inside the Shopify admin, choose Use a connector key instead on the sign-in page and paste the connector key from Settings > Other > AI connectors. The connector key only approves new connections; it is not an API key, and sending it as a header is rejected with a 401. Rotating it disconnects every assistant. Treat it like a password too.

The full setup for each assistant is in AI connectors (MCP).

Developer tools that cannot open a browser (Claude Code, Cursor, scripts) can skip OAuth and send the API key as a header to the MCP URL. Use that only for tools you run yourself.