Ihre API-Schlüssel verwalten

Mit einem API-Schlüssel kann ein externes Tool (CRM, Automatisierung mit Zapier oder Make, internes Skript, KI-Agent) die QR-Codes Ihres Kontos erstellen, lesen, bearbeiten, archivieren, reaktivieren oder löschen und ihre Statistiken sowie das verbleibende Erstellungskontingent lesen, ohne über das Dashboard zu gehen. Die technische Funktionsweise der API (Adressen, Formate, Fehlercodes) ist in der API-Dokumentation beschrieben. Diese Seite erklärt, wie Sie Ihre Schlüssel verwalten.

Der API-Zugriff ist in den Plänen Pro und Entreprise inbegriffen. Der Gratis-Plan bietet weder Zugriff auf die API noch einen Schlüssel.

Wo Sie Ihre Schlüssel verwalten

Die Schlüssel werden auf dem Bildschirm API-Schlüssel verwaltet, den Sie über die Karte API-Schlüssel des Bildschirms Abonnement erreichen (Schaltfläche API-Schlüssel verwalten).

• Der Bildschirm API-Schlüssel ist Mitgliedern mit der Berechtigung Verwalter der API-Schlüssel (oder Administrator) vorbehalten.
• Die Karte API-Schlüssel des Bildschirms Abonnement erscheint nur für Mitglieder, die sowohl Verwalter des Abonnements als auch Verwalter der API-Schlüssel haben (oder Administrator).

Einen Schlüssel erstellen

1. Geben Sie auf dem Bildschirm API-Schlüssel im Formular API-Schlüssel erstellen einen Namen des Schlüssels ein, an dem Sie ihn wiedererkennen, zum Beispiel «Zapier-Integration».
2. Wählen Sie unter Rechte des Schlüssels eine Voreinstellung oder Benutzerdefiniert (siehe unten).
3. Klicken Sie auf Schlüssel erstellen.
4. Der Bildschirm Kopieren Sie jetzt Ihren API-Schlüssel zeigt den vollständigen Schlüssel an, der mit qrs_live_ beginnt. Klicken Sie auf Kopieren und speichern Sie ihn an einem sicheren Ort, zum Beispiel im Passwort- oder Geheimnis-Manager Ihres Tools. Kreuzen Sie Ich habe meinen Schlüssel sicher gespeichert. an und klicken Sie dann auf Fertig.

Der vollständige Schlüssel wird nur ein einziges Mal angezeigt. Wir speichern ihn nicht im Klartext und können ihn Ihnen nicht erneut zusenden. Danach zeigt der Bildschirm nur noch seine letzten 4 Zeichen an (qrs_live_••••abcd). Wenn Sie ihn verlieren, führen Sie eine Rotation durch (siehe «Einen Schlüssel rotieren») oder erstellen Sie einen neuen.

Das Erstellen eines Schlüssels wird nie auf Ihr monatliches Kontingent angerechnet: Dieses gilt nur für QR-Codes, die über die API erstellt werden.

Ist die Höchstzahl an Schlüsseln Ihres Plans erreicht, erscheint das Formular zum Erstellen nicht mehr. Achtung: Beim Erstellen eines Schlüssels zählen eingefrorene Schlüssel zu diesem Limit (siehe «Eingefrorene Schlüssel»). Widerrufen Sie zuerst die Schlüssel, die Sie nicht mehr benötigen.

Den Schlüssel verwenden

Ihr Tool sendet den Schlüssel im Header jeder Anfrage: Authorization: Bearer qrs_live_…. Die API-Dokumentation beschreibt die verfügbaren Operationen und das jeweils erforderliche Recht.

Auf dem Bildschirm API-Schlüssel zeigt jeder Schlüssel sein Erstellungsdatum, das Datum seiner letzten Rotation und das seiner letzten Verwendung (oder Nie verwendet) an: praktisch, um einen Schlüssel zu erkennen, den kein Tool mehr verwendet. Dieses Datum wird höchstens einmal pro Minute aktualisiert. Eine Anfrage, die mangels Recht oder wegen Überschreitung des Rate-Limits abgelehnt wird, ändert es nicht.

Die Datumsangaben auf dem Bildschirm API-Schlüssel werden in Schweizer Zeit angezeigt. Die API hingegen liefert alle Datumsangaben in UTC, im Format ISO 8601: Das Z am Ende steht für UTC. Zum Beispiel entspricht 2026-10-17T22:12:00.000Z dem 18. Oktober 2026 um 00:12 Uhr in der Schweiz. Die Umrechnung in die gewünschte Zeitzone muss Ihr Tool übernehmen.

Die Rechte eines Schlüssels wählen

Ein Schlüssel kann nur tun, was seine Rechte erlauben. Geben Sie ihm nur die Rechte, die das Tool benötigt: Ein Schlüssel, der nur liest, kann weder QR-Codes erstellen noch löschen, selbst wenn er versehentlich an der falschen Stelle eingefügt wird.

Mit Benutzerdefiniert kreuzen Sie die gewünschten Rechte unter den 5 selbst an, mindestens eines.

Sie können die Rechte eines bestehenden Schlüssels jederzeit ändern und dann auf Rechte speichern klicken. Die Änderung gilt sofort, ohne dass sich der Schlüssel ändert: Das Tool, das ihn verwendet, muss nicht neu konfiguriert werden, es kann einfach mehr oder weniger tun.

Ein Aufruf, der eine von den Rechten des Schlüssels nicht erlaubte Operation verlangt, wird abgelehnt (Fehler 403 forbidden).

Zwei Operationen verlangen ein weniger offensichtliches Recht:

• Archivieren oder Reaktivieren eines QR-Codes verlangt QR-Codes bearbeiten;
• Abrufen des Erstellungskontingents (Erstellungen des Monats, Stand der Pakete) verlangt QR-Codes erstellen. Die Voreinstellungen Lesen / Reporting und KI-Assistent können diesen Stand daher nicht abrufen.

Erstellungskontingente und Pakete

Gezählt wird nur das Erstellen eines QR-Codes über die API: Einen QR-Code lesen, bearbeiten, archivieren, reaktivieren oder löschen, sein Bild herunterladen oder seine Statistiken lesen wird nicht gezählt. Auch im Dashboard erstellte QR-Codes werden nicht gezählt.

• Das Kontingent beträgt 5 Erstellungen pro Kalendermonat mit dem Plan Pro und 100 mit dem Plan Entreprise, für das ganze Konto (alle Schlüssel zusammen).
• Eine Erstellung bleibt gezählt, auch wenn Sie den QR-Code danach löschen: Das Löschen eines QR-Codes gibt Ihnen keine Erstellung zurück.
• Es wird am 1. jedes Monats um 00:00 Uhr UTC zurückgesetzt, also um 01:00 Uhr Schweizer Zeit (02:00 Uhr während der Sommerzeit). Nicht genutzte Erstellungen werden nicht übertragen.
• Ist das Kontingent des Monats aufgebraucht, verbraucht jede Erstellung eine Erstellung aus Ihren API-Erstellungspaketen, beginnend mit dem ältesten Paket.
• Sind das Kontingent des Monats und alle Ihre Pakete aufgebraucht, wird die Erstellung mit dem Fehler 429 quota_exceeded abgelehnt, der das Datum der Zurücksetzung des Kontingents angibt. Es wird nichts nach Verbrauch abgerechnet.

Der Bildschirm API-Schlüssel zeigt Ihren aktuellen Stand: genutzte Erstellungen des Monatskontingents, aus Ihren Paketen genommene Erstellungen, verbleibende Erstellungen in Ihren Paketen und das Datum der nächsten Zurücksetzung. Ihr Tool kann dieselben Zahlen mit GET /usage abrufen, mit einem Schlüssel, der das Recht QR-Codes erstellen hat (siehe API-Dokumentation).

Die Pakete (+50, +100, +500, +1000 oder +5000 Erstellungen) werden einmalig über die Karte API-Erstellungspakete des Bildschirms Abonnement gekauft, sofern ein Pro- oder Entreprise-Abonnement aktiv ist. Sie verfallen nicht, solange Ihr Konto im Plan Pro oder Entreprise bleibt. Die Preise finden Sie auf der Seite Preise; die Kaufbedingungen und das Einfrieren im Gratis-Plan sind unter Abonnement verwalten beschrieben.

Einen Schlüssel rotieren

Die Schaltfläche Rotation erzeugt ein neues Geheimnis für den Schlüssel und macht das alte sofort ungültig. Der Schlüssel behält seinen Namen und seine Rechte und zählt nicht als zusätzlicher Schlüssel.

1. Klicken Sie neben dem Schlüssel auf Rotation und bestätigen Sie.
2. Kopieren Sie den neuen Schlüssel auf dem Bildschirm Kopieren Sie jetzt Ihren API-Schlüssel: Wie beim Erstellen wird er nur ein einziges Mal angezeigt.
3. Ersetzen Sie den alten Schlüssel in allen Tools, die ihn verwenden: Solange Sie das nicht getan haben, werden ihre Aufrufe abgelehnt.

Rotieren Sie einen Schlüssel, wenn Sie ihn verloren haben, wenn Sie vermuten, dass er offengelegt worden sein könnte (per E-Mail versendet, in einem Code-Repository veröffentlicht, auf einem Screenshot sichtbar), oder einfach in regelmässigen Abständen.

Einen Schlüssel widerrufen

Die Schaltfläche Widerrufen macht den Schlüssel sofort und endgültig unbrauchbar. Die Tools, die ihn verwenden, funktionieren sofort nicht mehr. Ein widerrufener Schlüssel verschwindet aus der Liste und kann weder reaktiviert noch rotiert werden.

Der Widerruf betrifft weder Ihre QR-Codes, auch nicht die mit diesem Schlüssel erstellten, noch Ihr Kontingent, noch Ihre Pakete. Er gibt einen Platz im Schlüssel-Limit Ihres Plans frei: Sie können danach einen neuen Schlüssel erstellen.

Widerrufen Sie einen Schlüssel, sobald ein Tool ihn nicht mehr benötigt, oder wenn er offengelegt worden sein könnte und kein Tool ihn mehr verwenden soll.

Eingefrorene Schlüssel

Ein eingefrorener Schlüssel lehnt alle Aufrufe der API ab, auch zum Lesen, mit demselben Fehler wie ein ungültiger Schlüssel (401 unauthorized). Er ist weder widerrufen noch gelöscht: Sein Name und seine Rechte bleiben erhalten. Ein Schlüssel wird eingefroren, wenn Ihr Plan weniger Schlüssel erlaubt, als Sie haben. Die Administratoren des Kontos werden per E-Mail darüber informiert, und ein Banner weist im Dashboard darauf hin.

Wenn Ihr Konto in den Gratis-Plan wechselt

Endet Ihr Pro- oder Entreprise-Abonnement (Kündigung zum Ablaufdatum oder endgültig fehlgeschlagene Zahlung), werden alle Ihre Schlüssel eingefroren: Die Tools, die sie verwenden, funktionieren nicht mehr. Auch das Guthaben Ihrer Erstellungspakete wird eingefroren, ohne verloren zu gehen.

Im Gratis-Plan zeigt der Bildschirm API-Schlüssel Ihre Schlüssel nicht an: Sie können sie weder einsehen noch widerrufen, rotieren oder reaktivieren.

Sobald Sie wieder ein Pro- oder Entreprise-Abonnement abschliessen, werden Ihre eingefrorenen Schlüssel automatisch wieder verwendbar, im Rahmen des neuen Plans: zuerst diejenigen, die beim Einfrieren aktiv waren, dann die ältesten. Schlüssel über dem Limit bleiben eingefroren.

Wenn Sie vom Plan Entreprise zum Plan Pro wechseln

Der Plan Pro erlaubt nur einen aktiven Schlüssel. Am Datum des Wechsels bleibt der älteste Schlüssel (nach Erstellungsdatum) aktiv, die anderen werden eingefroren. Sie bleiben auf dem Bildschirm API-Schlüssel mit dem Abzeichen Eingefroren sichtbar. Wechseln Sie wieder zum Plan Entreprise, werden sie automatisch wieder aktiv.

Den aktiven Schlüssel wählen

Solange sich Ihr Plan nicht ändert, wird kein eingefrorener Schlüssel automatisch reaktiviert. Sie wählen selbst:

• Die Schaltfläche Reaktivieren erscheint neben jedem eingefrorenen Schlüssel, solange die Anzahl Ihrer aktiven Schlüssel unter dem Limit Ihres Plans liegt. Im Plan Pro widerrufen Sie also zuerst den aktiven Schlüssel, falls es einen gibt (der Widerruf ist endgültig).
• Der reaktivierte Schlüssel funktioniert sofort wieder, mit unverändertem Wert und unveränderten Rechten. Falls er offengelegt worden sein könnte, rotieren Sie ihn gleich danach.
• Eine Rotation reaktiviert einen eingefrorenen Schlüssel nicht: Er bleibt eingefroren.

Widerruf durch QR Suisse

QR Suisse kann alle API-Schlüssel Ihres Kontos widerrufen, aktive wie eingefrorene, auf Anfrage eines Administrators des Kontos (schreiben Sie an contact@qrsuisse.ch von der E-Mail-Adresse aus, die Sie für QR Suisse verwenden) oder wenn ein Schlüssel einem Dritten offengelegt oder ohne Ihre Zustimmung verwendet worden sein könnte. Das ist insbesondere die Lösung, wenn ein Schlüssel offengelegt wurde, während Ihr Konto im Gratis-Plan ist, in dem Sie ihn nicht selbst widerrufen können.

Dieser Widerruf ist sofort wirksam und endgültig, wie ein Widerruf durch Sie selbst. Die Administratoren des Kontos werden per E-Mail darüber informiert. Ihre QR-Codes, Ihr Kontingent und Ihre Pakete sind nicht betroffen. Im Plan Pro oder Entreprise können Sie sofort neue Schlüssel erstellen. Ein widerrufener eingefrorener Schlüssel wird nicht reaktiviert, wenn Sie wieder ein Abonnement abschliessen.

Rate-Limit und Fehler 429

Zum Schutz des Dienstes gilt für die Anzahl der Aufrufe ein Limit, jeweils über Zeitfenster von 60 Sekunden:

Darüber hinaus antwortet die API mit 429 rate_limited und einem Header Retry-After, der in Sekunden angibt, wann Sie es erneut versuchen können. Programmieren Sie Ihr Tool so, dass es diese Zeit abwartet, statt den Aufruf sofort zu wiederholen.

Auch für Aufrufe, die wegen eines ungültigen Schlüssels abgelehnt werden (401 unauthorized), gilt ein Limit: 60 pro Minute von derselben IP-Adresse aus und 300 pro Minute für ein ganzes IPv6-Netz /48. Darüber hinaus antwortet die API für den Rest der Minute mit 429 rate_limited, auch mit einem gültigen Schlüssel. Ein falsch konfiguriertes Tool, das es mit einem alten Schlüssel immer wieder versucht, kann also die anderen Tools, die die API von derselben Adresse aus aufrufen, vorübergehend blockieren.

Verwechseln Sie die beiden Fehler 429 nicht: rate_limited bedeutet «zu viele Aufrufe in kurzer Zeit, versuchen Sie es in einigen Sekunden erneut», quota_exceeded bedeutet «in diesem Monat keine Erstellung mehr verfügbar» (siehe «Erstellungskontingente und Pakete»).

Häufige Fragen

Ich habe meinen Schlüssel verloren: Kann ich ihn wiederfinden?

Nein. Der vollständige Schlüssel wird nur ein einziges Mal angezeigt, und wir speichern ihn nicht im Klartext. Führen Sie mit der Schaltfläche Rotation eine Rotation durch: Sie erhalten einen neuen Schlüssel mit demselben Namen und denselben Rechten. Denken Sie daran, ihn in allen Tools zu ersetzen, die den alten verwendet haben.

Warum antwortet die API mit 401, obwohl ich meinen Schlüssel verwende?

Die API antwortet in all diesen Fällen mit 401 unauthorized, ohne sie zu unterscheiden: falsch kopierter oder unvollständiger Schlüssel, widerrufener Schlüssel, Schlüssel, dessen Geheimnis sich nach einer Rotation geändert hat, oder eingefrorener Schlüssel (zum Beispiel weil Ihr Konto in den Gratis-Plan gewechselt hat). Prüfen Sie auf dem Bildschirm API-Schlüssel, ob der Schlüssel noch existiert, ob er nicht das Abzeichen Eingefroren trägt und ob seine letzten 4 Zeichen mit denen des verwendeten Schlüssels übereinstimmen.

Warum antwortet die API mit 403?

Mit forbidden ist der Schlüssel gültig, aber seine Rechte erlauben die verlangte Operation nicht: Ergänzen Sie das fehlende Recht unter Rechte des Schlüssels und klicken Sie auf Rechte speichern. Mit account_disabled ist das Konto ausgesetzt oder wartet auf die Löschung: Der Schlüssel ist nicht die Ursache, schreiben Sie an contact@qrsuisse.ch. Mit plan_required hat das Konto keinen aktiven Pro- oder Entreprise-Plan mehr. Mit https_required hat Ihr Tool die API über http:// statt https:// aufgerufen: Die Anfrage wurde nicht verarbeitet, aber der Schlüssel wurde unverschlüsselt übertragen. Korrigieren Sie die Adresse auf https://app.qrsuisse.ch/api/v1 und rotieren Sie den Schlüssel dann mit der Schaltfläche Rotation.

Was bedeutet der Fehler 429?

Mit rate_limited hat Ihr Tool zu viele Anfragen in kurzer Zeit gesendet: Warten Sie die im Header Retry-After angegebene Zeit ab und versuchen Sie es dann erneut. Mit quota_exceeded sind das Erstellungskontingent des Monats und Ihre Pakete aufgebraucht: Das Erstellen ist am 1. des Folgemonats wieder möglich oder sobald Sie ein Paket kaufen.

Eine Erstellung wurde durch einen Netzwerkunterbruch unterbrochen: Wie sende ich sie ohne Duplikat erneut?

Wenn Ihr Tool bei jeder Erstellung den Header Idempotency-Key mitsendet (ein neuer Zufallswert pro Erstellung), kann es dieselbe Anfrage mit demselben Wert innerhalb von 24 Stunden erneut senden: Die API gibt den bereits erstellten QR-Code zurück, ohne einen zweiten zu erstellen oder eine weitere Erstellung anzurechnen. Ohne diesen Header prüfen Sie die Liste Ihrer QR-Codes, bevor Sie die Anfrage erneut senden: Eine erfolgreiche Erstellung bleibt angerechnet, auch wenn Sie das Duplikat danach löschen. Die Einzelheiten stehen in der API-Dokumentation.

Wird das Erstellen eines Schlüssels auf mein Kontingent angerechnet?

Nein. Nur über die API erstellte QR-Codes werden auf das monatliche Kontingent angerechnet.

Werden meine über die API erstellten QR-Codes gelöscht, wenn ich den Schlüssel widerrufe?

Nein. Der Widerruf eines Schlüssels ändert oder löscht keinen QR-Code. Die mit diesem Schlüssel erstellten QR-Codes funktionieren weiter.

Warum sehe ich den Bildschirm API-Schlüssel nicht?

Der Bildschirm API-Schlüssel ist Mitgliedern mit der Berechtigung Verwalter der API-Schlüssel (oder Administrator) vorbehalten. Im Gratis-Plan weist er darauf hin, dass der API-Zugriff mit den Plänen Pro und Entreprise verfügbar ist, und allfällige eingefrorene Schlüssel werden dort nicht angezeigt. Bitten Sie einen Administrator des Kontos, Ihnen die Berechtigung zu erteilen oder zum Plan Pro zu wechseln.

Mein Schlüssel wurde möglicherweise offengelegt: Was tun?

Rotieren Sie ihn sofort mit der Schaltfläche Rotation, wenn Ihre Tools ihn weiter verwenden sollen, oder widerrufen Sie ihn sonst mit der Schaltfläche Widerrufen. In beiden Fällen funktioniert der alte Schlüssel sofort nicht mehr. Können Sie das nicht selbst tun, zum Beispiel weil Ihr Konto im Gratis-Plan ist, schreiben Sie an contact@qrsuisse.ch von der E-Mail-Adresse eines Administrators des Kontos aus.

Wie viele Schlüssel kann ich haben?

Einen aktiven Schlüssel mit dem Plan Pro, bis zu 10 gleichzeitig aktive Schlüssel mit dem Plan Entreprise. Um einen neuen Schlüssel zu erstellen, zählen auch Ihre eingefrorenen Schlüssel zu diesem Limit, solange Sie sie nicht widerrufen haben.

Siehe auch

• API-Dokumentation
• Abonnement verwalten
• Benutzer verwalten
• Kontostatus verstehen