The shop API: your first request
Make a key with only what your server needs, send it from your server, and read your shop.
Make a key (store owner)
Dashboard → Settings → Developers → API keys → Make a key. Choose only the permissions (scopes) your server needs, optionally the addresses it calls from, and how long the key works. Confirm with your password (and your 2-step code). Copy the key — it is shown once.
Keep it on your server
Put it in your server’s secret settings (an environment variable). Never in a web page, an app or a repository — Tocler refuses calls from browsers.
Send your first request
Read the key itself —
GET /v1/keyneeds no scope and tells you what the key may do.
curl https://api.tocler.com/v1/key \
-H "Authorization: Bearer $TOCLER_KEY"const res = await fetch('https://api.tocler.com/v1/key', {
headers: { Authorization: `Bearer ${process.env.TOCLER_KEY}` },
});
const key = await res.json();
console.log(key.scopes, key.expires_at, res.headers.get('RateLimit-Remaining'));import os, requests
r = requests.get('https://api.tocler.com/v1/key', headers={'Authorization': 'Bearer ' + os.environ['TOCLER_KEY']}, timeout=15)
print(r.json()['scopes'])<?php
$ch = curl_init('https://api.tocler.com/v1/key');
curl_setopt_array($ch, [CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('TOCLER_KEY')], CURLOPT_RETURNTRANSFER => true]);
$key = json_decode(curl_exec($ch), true);Changing things safely
Every POST and PATCH needs an Idempotency-Key header — make one per action (for example your own cart or order id) and send the same one when you retry after a timeout. Tocler then answers with the first result instead of doing it twice.
Errors you will meet
401 invalid_key/key_revoked/key_expired— the key. Rotate it in the Dashboard.403 missing_scope— the key wasn’t given that permission. Make a key with it.403 ip_not_allowed— the call came from an address not on the key’s list.429 rate_limited— waitRetry-Afterseconds.409 conflict— something changed meanwhile (a sale took the stock you saw). Read again.
Rotating a key
Rotate makes a new key with the same permissions; the old one can keep working up to 24 hours so you can switch without a gap. You get an email 14 days before a key expires, and every new or revoked key is emailed to the store owner.