How to create an API key for your store

An API key lets your own code, scripts or applications talk to your store through the FreshStore Store API. This guide covers creating a key, choosing its permissions, using it, and revoking it later.

Before you start

• You need access to the store admin area of the store you want the key for. A key belongs to one store.
• Using the API needs some technical knowledge.

Create the key

1. Log in to the store admin area of that store. This is your store's own dashboard, not your FreshStore account area at my.freshstore.com.
2. Go to Settings > API Keys in the store admin area.
3. Click Create API Key.
4. Enter a Key Name that tells you what the key is for, for example "Mobile App" or "Reporting script".
5. Tick the Permissions the key needs. See the section below.
6. Optionally set an Expires At date. Leave it empty for a key that never expires.
7. Create the key, then copy it immediately.

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, store and data, which are read only.

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 store domain, so a request looks like https://your-store-domain.com/api/products.

Requests are limited to 60 per minute, counted separately for each store and each API key. Going over that returns 429 Too Many Requests.

Reviewing and revoking keys

The Settings > API Keys page in the store 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

• 401 Unauthorized: the key is missing, wrong, expired or revoked. Check the Authorization header is exactly Bearer YOUR_API_KEY.
• 403 Forbidden with a message about read or write access: the key's permissions are too narrow for that request.
• 403 Forbidden with no API message: your request was blocked by the firewall. Set a browser User-Agent, and if it still fails, contact support with your server IP address.
• 404 Not Found with "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.

The full list of endpoints, fields and example responses is in the FreshStore Store API endpoint reference.