How to create an API key for your site
An API key lets your own code, scripts or applications talk to your site through the FreshStore Site API. This guide covers creating a key, choosing its permissions, using it, and revoking it later.
Before you start
- You need access to the site admin area of the site you want the key for. A key belongs to one site.
- Using the API needs some technical knowledge.
Create the key
- Log in to the site admin area of that site. This is your site's own dashboard, not your FreshStore account area at my.freshstore.com.
- Go to Settings > API Keys in the site admin area.
- Click Create API Key.
- Enter a Key Name that tells you what the key is for, for example "Mobile App" or "Reporting script".
- Tick the Permissions the key needs. See the section below. For an AI tool, choose a Preset instead and it ticks them for you.
- Optionally set an Expires At date. Leave it empty for a key that never expires.
- Create the key, then copy it immediately.
The key is shown once. Copy it and store it somewhere safe as soon as you create it. It cannot be shown again. If you lose it, revoke it and create a new one.
Choosing permissions
You have three levels to choose from:
- Full Access: read and write everything.
- Read or Write: broad read or write access across all resources.
- Per resource: granular access such as "Products: Read" or "Offers: Write". The resources are products, offers, categories, brands, articles, article categories, pages, settings and users, plus analytics, site and data, which are read only. A key with only per-resource boxes is refused, so tick Read or Write as well.
Give each key the smallest set of permissions that does its job. If a request asks for more than the key allows, the API replies 403 Forbidden with a message such as This token does not have write access.
Using the key
Send the key as a bearer token in the Authorization header of every request:
Authorization: Bearer YOUR_API_KEY
The base URL is your own site domain, so a request looks like https://your-store-domain.com/api/products.
Requests are limited to 60 per minute, counted separately for each site and each API key. Going over that returns 429 Too Many Requests.
Requests that carry an API key get through with the default User-Agent of curl, python-requests and other common libraries. You can send a User-Agent that names your tool, for example MyStoreScript/1.0.
Reviewing and revoking keys
The Settings > API Keys page in the site admin area lists every key with its name, owner, permissions, when it was last used, when it expires and when it was created. Last Used is the quickest way to spot a key nothing needs any more.
To revoke a key, click Revoke on its row and confirm. Any application using that key loses access immediately, so check what depends on it first.
Troubleshooting
403 Forbiddenwith{"error": "Forbidden"}: the key is missing, wrong, expired or revoked. Check theAuthorizationheader is exactlyBearer YOUR_API_KEY.403 Forbiddenwith a message about read or write access: the key's permissions are too narrow for that request.403 Forbiddenwith a web page in place of JSON: set a User-Agent that names your tool, for exampleMyStoreScript/1.0. If it still fails, contact support with your server IP address.404 Not Foundwith "The API resource was not found": the path is wrong.429 Too Many Requests: you are over 60 requests per minute. Slow the requests down.
Connecting Claude, ChatGPT, Codex, Cursor or another AI agent? Follow How to connect Claude, ChatGPT and other AI tools to your site. It uses the same key, made from a preset.
The full list of endpoints, fields and example responses is in the FreshStore Site API endpoint reference.