Overview
An API key lets another system connect to your store. A developer, an ERP, a warehouse system or your own mobile app uses the key to read or change your store’s data through the Shopcada API.
You can:
- Create a separate key for each app that connects to your store
- Choose, for each area of your store, whether the key may read, write or delete
- Copy a key with one click to hand it to your developer
- Switch a key off without deleting it, and switch it back on later
- Rename a key or change its permissions at any time
- Delete a key the moment an app no longer needs it
This document cover:
Where API Keys Live
Navigate to Settings > Integrations, then click the Api Key Manager tab.
You need the Configure Store permission to open this tab. The tab lists every API key in your store.
| Column | What it shows |
|---|---|
| Name | The name you gave the key. |
| API Key | The full key, with a copy icon beside it. |
| Active | Yes if apps can use the key. No if you switched it off. |
| Created | The date and time the key was created. |
| Updated | The date and time someone last changed the key’s name, status or permissions. |
The edit and delete icons sit at the end of each row.
Before You Begin
- Ask the developer what the app needs.
You grant access one area at a time. Find out which areas the app uses, and whether it only reads data or also makes changes. - Plan one key per app.
You can then switch off or delete one app’s access without breaking the others. - Decide how you will send the key.
An API key works like a password. Send it privately, the same way you would send a password.
Creating an API Key
Step 1: Open the form
- On the Api Key Manager tab, click New Api Key.
The Add Apikey window opens.
Step 2: Name the key
- Enter a Name.
Name it after the app or company that will use it, for example Warehouse system or Mobile app. The name is required.
Step 3: Tick the permissions
- In the permission table, tick Read, Write or Delete against each Permission Group the app needs.
Every box starts unticked. See Choosing Permissions for what each box allows. - Leave a group unticked if the app does not use it.
Step 4: Save the key
- Read the notes under the table.
Clicking Save confirms that you accept full responsibility for how the key is used. - Click Save.
The message Api Key created successfully appears, and the new key is in the list.
A new key is active the moment you save it. Any app holding the key can use it straight away.
Choosing Permissions
Each Permission Group is one area of your store. The three boxes decide what the app may do in that area.
| Box | Allows the app to |
|---|---|
| Read | View records. |
| Write | Create new records and change existing ones. |
| Delete | Delete records, or cancel them where the record is an order or a reservation. |
What each group covers
| Permission Group | Read | Write | Delete |
|---|---|---|---|
| Customers | Customer accounts, addresses and wishlists; gift certificate, store credit and Reward Points balances; carts; reservations | Create and update customer accounts; sign customers in and out, and reset passwords; add or deduct Reward Points; change the remaining amount and expiry of gift certificates and store credit; add items to carts; create reservations | Delete customer accounts and wishlist items; remove cart items; cancel reservations |
| Products | Products and variants; categories, collections, brands and colours | Create and update products; add and update variants | Delete products and variants |
| Inventory | Stock levels; inventory locations; transfer orders | Set and adjust stock levels; create and update transfer orders | Not used — no inventory action deletes anything |
| Orders | Orders; order statuses; order tags; refunds | Create and update orders; add order tags | Cancel orders; remove order tags |
| Fulfilments | Shipments; carriers | Create shipments and update their status | Not used — no fulfilment action deletes anything |
A few calls need no ticked box. Any active key can read your outlet list and your lookbooks, and load your Shopcada mobile app settings.
Good to know
- Signing customers in counts as Write.
An app that lets customers log in needs Customers > Write, not only Read. Adding items to a cart needs it too. - Customers > Write can change customer balances.
The same box that allows sign-in also allows Reward Points, store credit and gift certificate changes. You cannot grant one without the other, so tick it only for an app you trust with those balances. - A permission covers the whole area.
You cannot limit a key to one outlet, one category or one customer group. - Permission changes apply on the app’s next call.
The app keeps the same key.
Copying a Key
- On the Api Key Manager tab, click the copy icon beside the key.
- Your browser shows API key copied to your clipboard!
If it shows Failed to copy!, select the key with your mouse and copy it yourself. - Paste the key into the private channel you agreed with your developer.
Editing a Key
- Click the edit icon on the key’s row.
The Edit Api Key window opens. - Change the Name, the Api Key Active box or the permission table.
- Click Save.
The message Api Key updated successfully appears.
The key itself cannot be changed. The window shows it at the top for reference only, and there is no button to generate a new value. See Replacing a Key.
Switching a Key Off
Switch a key off to pause an app’s access without losing the key.
- Click the edit icon on the key’s row.
- Untick Api Key Active.
- Click Save.
The Active column now reads No.
From that moment the store refuses every call made with the key. Tick Api Key Active again to restore access. The key and its permissions stay as they were.
Deleting a Key
- Click the delete icon on the key’s row.
The Delete Api Key window asks Are you sure you want to delete <key name>? - Type DELETE in the text box, in capital letters.
Any other text shows Please enter DELETE in this textbox to confirm the removal. - Click Confirm.
The message Api Key <key name> deleted successfully. appears.
Deleting cannot be undone. The app stops working at once, and the key cannot be restored. If you are not sure the app is finished with it, switch the key off instead.
Replacing a Key
Replace a key when it may have leaked, or when a developer who held it leaves.
- Create a new key with the same permissions.
See Creating an API Key. - Give the new key to the developer, and wait until the app runs on it.
- Delete the old key.
If the key has leaked, switch the old key off first. The app stops until the new key is in place, but nobody can use the leaked key in the meantime.
Details for Your Developer
Send these details with the key.
| Item | Value |
|---|---|
| API documentation | api-doc.shopcada.com/apiv3.html |
| API address | https://www.your-domain.com/api/v3/ — using your store’s own domain |
| Where the key goes | In the X-Shopcada-API-Key header of every call |
When the app reports an error
| Error | Means | What to do |
|---|---|---|
| X-Shopcada-API-Key header not found | The call did not include a key. | The developer adds the key to the header. |
| Invalid api key given. | The key is wrong, deleted or switched off. | Check the key is in the list and Active reads Yes. Copy it again and resend it. |
| Invalid API Key Permission | The key works, but its permissions do not allow this action. | Edit the key and tick the box the action needs. |
Important Notes
- Anyone who can open this tab can copy every key.
The list shows each key in full to every staff member with the Configure Store permission. Give that permission only to people you trust with your store’s data. - Keys never expire.
A key works until you switch it off or delete it. Review the list regularly, and delete keys for apps you no longer use. - The list does not show when a key was last used.
Updated is the last time someone edited the key, not the last time an app used it. - Tick only what the app needs.
Customers > Write in particular lets an app change Reward Points, store credit and gift certificate balances. - Never put a key in website code.
A key belongs on the developer’s server. Anyone can read a key placed in your theme, a public code repository or a web page. - API Apps is a separate tab.
The API Apps tab on the same Integrations page lists apps you approved through a sign-in screen. Those apps do not use an API key, and deleting a key does not affect them.
