How do API keys, scopes, IP allowlists and rate limits work?
Updated September 14, 2026 · 3 min read · Pro and Business
API keys are created on the API page under Settings → Developer settings in the dashboard. Each key carries its own scopes, can be restricted to a list of IP addresses or CIDR ranges, and is shown once at creation — we keep only a hash, so a lost key has to be replaced. You can hold five active keys at a time, and revoking one stops every request using it immediately.
Create a key
- Go to Settings → Developer settings → API. The heading reads API keys and shows how many of your five slots are in use.
- Click New key.
- Give it a Name — name it after the system that will hold it, so you know what breaks when you revoke it.
- Tick the Scopes it needs.
- Optionally fill in the IP allowlist.
- Click Create key, then copy the value.
The dialog says it plainly: copy your key now, for security it cannot be shown again. There is no way to reveal or edit an existing key — not its value and not its scopes. To change either, revoke it and create a new one.
Keys start with qrs_. The dashboard list shows only the first eight characters, which identify the key but cannot authenticate anything.
What each scope allows
| Scope | What it allows |
|---|---|
qr:read | List and view QR codes |
qr:write | Create, edit and delete QR codes |
qr:bulk | Bulk-create QR codes (Business) |
links:read | List and view short links |
links:write | Create, edit and delete short links |
analytics:read | Read scan analytics |
qr:read, qr:write and analytics:read are pre-ticked. The link scopes are not, which is the single most common surprise: a key made with the defaults returns 403 SCOPE_DENIED the first time it calls /links. Give each integration the narrowest set that does its job — a reporting script rarely needs anything but qr:read and analytics:read.
Locking a key to an IP range
The IP allowlist box takes plain addresses or CIDR ranges, one per line — for example 203.0.113.4 or 10.0.0.0/24. Both IPv4 and IPv6 work, and you can list up to 50 entries. Leave it empty to allow requests from anywhere.
A request arriving from an address outside the list is rejected with 403 and the code IP_NOT_ALLOWED, whatever its scopes. This is worth doing for a key that lives on a fixed server, and worth avoiding for anything running on a laptop or a platform with rotating egress addresses.
Rate limits and 429s
| Plan | Per minute | Per month |
|---|---|---|
| Pro | 60 | 5,000 |
| Business | 600 | 100,000 |
The per-minute limit is counted per key, so splitting work across two keys on the same account does not raise your ceiling in any useful way — the monthly quota is counted per key too, and every request to /api/v1 counts, including the ones that fail validation.
Both limits return 429. The body tells you which: RATE_LIMITED_PER_MINUTE clears within the minute, and RATE_LIMITED_PER_MONTH says the monthly quota is used up and resets on the 1st. Responses also carry X-RateLimit-Limit and X-RateLimit-Remaining for the monthly quota, so a long-running job can slow itself down before it hits the wall.
Revoking a key
Click Revoke on the key's row. The confirmation says it exactly: any integration using it will stop working immediately. There is no grace period and no undo, and the key leaves the list.
Revoke a key whenever it has been pasted somewhere it should not have been, when the system holding it is retired, or when you need different scopes. Each row shows a call count and when it was last used, which is the quickest way to tell whether a key is still in service before you pull it.
Common problems
New key returns 403 API access requires a Pro or Business plan
The key is fine; the plan is not. API access is on Pro and Business only.
403 API key is missing required scope
The response names the scope it needed and lists the ones granted. Scopes are fixed at creation, so revoke and recreate.
The New key button is greyed out
You already have five active keys. Revoke one to free a slot.
Requests fail from a new server
If the key has an IP allowlist, the new server's outbound address has to be in it. Check for IP_NOT_ALLOWED in the response body before hunting elsewhere.
Frequently asked questions
I lost my key. Can I see it again?
No. Only a hash is stored, so the value cannot be recovered. Revoke the key and create a replacement.
Can I change a key's scopes later?
No. Scopes and the IP allowlist are set at creation. To change either, revoke the key and create a new one.
How many keys can I have?
Five active keys per account. Revoked keys do not count against the limit.
Do failed requests count against my quota?
Yes. Every request to /api/v1 increments the monthly counter for that key, including validation errors.
Do keys work on the Starter plan or the free trial?
No. The API is Pro and Business only, and every endpoint returns 403 PLAN_NOT_ALLOWED on other plans.
Related articles
How do I get started with the QRCodeStack API?
Create a key under Settings → Developer settings → API, send it as Authorization: Bearer qrs_…, and call GET /api/v1/me. Pro and Business only.
How do I use the audit log and SSO settings?
Settings → Audit log shows who did what, when and from which IP, for admins and owners. CSV export is on Business. Domain sign-in lives under Identity and SSO.
How do I turn on two-factor authentication?
Settings → Security → Enable 2FA. Scan the QR code with an authenticator app, enter the 6-digit code, then save the 10 backup codes shown once.
How do I replace the Google Charts QR code API?
The Charts image API is deprecated. Create the code once with POST /api/v1/qr-codes, then fetch GET /qr-codes/{id}/image with your key and store the file.
Still stuck?
Email support@qrcodestack.com with the email on your account and, if it is about one code, its name or short link. A person replies within one business day, usually sooner.