Ein API-Schlüssel authentifiziert Ihre Anfragen an die Simbase-API. Jeder Schlüssel verfügt über eine Reihe von Berechtigungen, die bei seiner Erstellung ausgewählt werden und die fortan feststehen. Ein Schlüssel kann für mehrere Integrationen verwendet werden, doch die sicherere Vorgehensweise ist ein eigener Schlüssel pro Integration. Schlüssel werden im Dashboard unter „Integrationen → API“ erstellt und verwaltet.

API-Schlüssel erstellen

1. Anmelden bei dashboard.simbase.com.

2. Gehen Sie zu „Integrationen“ → „API“.

3. Klicken Sie auf „Neuen API-Schlüssel erstellen“.

4. Geben Sie dem Schlüssel einen Namen, der seinen Zweck beschreibt, zum Beispiel Usage Guard Toolkit. Der Name ist nur eine Bezeichnung. Er erscheint in Ihrer Schlüsselliste und sonst nirgendwo.

5. Legen Sie unter „Ressourcen“ die Berechtigungen fest, die der Schlüssel benötigt. Siehe Berechtigungen unten.

6. Klicken Sie auf „API-Schlüssel erstellen“ und kopieren Sie anschließend den Schlüssel.

In der folgenden Demo finden Sie eine Schritt-für-Schritt-Anleitung:

Berechtigungen

Berechtigungen werden pro Ressource auf einer von drei Ebenen festgelegt. Keine bedeutet, dass der Schlüssel diese Ressource überhaupt nicht berühren darf, und dies ist die Standardeinstellung für jede Zeile. Lesen ruft Daten ab und nimmt keine Änderungen vor. Schreiben erstellt, aktualisiert und löscht; wenn man diese Option auswählt, wird gleichzeitig „Lesen“ in derselben Zeile ausgewählt, da jeder Schreibvorgang zunächst einen Lesevorgang erfordert.

Nicht jede Ressource bietet alle drei Optionen an. „Konto“ und „Nutzung“ sind schreibgeschützt, daher werden dort „Keine“ und „Lesen“ angezeigt. „SIM-Kartenstatus“, „Zurücksetzen“, „Registrierung“ und „Automatische Deaktivierung“ sind Aktionen und keine Daten, daher werden dort „Keine“ und „Schreiben“ angezeigt.

Der Ressourcenbaum

Über- und Unterzeilen

Neben den Bezeichnungen „SIM-Karten“, „Dienstprogramme“ und „Integrationen“ befindet sich jeweils ein Pfeil. Klicken Sie darauf, um die darunter liegenden einzelnen Berechtigungen anzuzeigen.

• Durch das Festlegen eines übergeordneten Elements werden alle untergeordneten Elemente auf dieselbe Berechtigungsstufe oder auf die höchste von ihnen unterstützte Berechtigungsstufe gesetzt. Wenn für alle Ressourcen die Berechtigung „Schreiben“ festgelegt wird, erhalten „Konto“ und „Nutzung“ die Berechtigung „Lesen“, da „Lesen“ die höchste von ihnen unterstützte Berechtigungsstufe ist.

• Wird ein untergeordnetes Element auf „none“ gesetzt, wird bei dem übergeordneten Element nichts ausgewählt angezeigt. Das ist beabsichtigt. Ein übergeordnetes Element zeigt eine Ebene nur dann an, wenn alle seine untergeordneten Elemente übereinstimmen.

Auswahl eines Levels

Stelle das absolute Minimum bereit, das für die Integration erforderlich ist. Ein Schlüssel, der nur zum Auslesen von Nutzungsdaten dient, kann eine SIM-Karte nicht deaktivieren, falls Daten nach außen gelangen.

In der API-Referenz erscheinen diese als Bereichsnamen, die aus demselben Baum aufgebaut sind. Die SIM-Kartendaten werden zugeordnet an simcards.details:read und simcards.details:write.

Erweiterte Einstellungen

Aktivieren Sie die Option „Erweiterte Einstellungen anzeigen“, um zwei optionale Felder einzublenden. Beide Felder können leer gelassen werden.

IP-Einschränkungen

Beschränkt den Schlüssel auf eine einzelne vertrauenswürdige IP-Adresse oder einen Adressbereich in CIDR-Notation. Anfragen von anderen Adressen werden abgelehnt. Lassen Sie das Feld leer, wenn keine Einschränkung gelten soll. Die Schlüsselliste zeigt dann 0.0.0.0/0 unter „Zulässige IP-Adressen“, was bedeutet, dass jede Adresse zulässig ist.

Läuft in (Anzahl der Tage) ab

Die Anzahl der Tage vom Erstellungsdatum bis zum Zeitpunkt, an dem der Schlüssel nicht mehr funktioniert. Geben Sie 31 und der Schlüssel läuft in 31 Tagen ab. Wenn Sie das Feld leer lassen, läuft der Schlüssel nie ab.

Kurzlebige Schlüssel eignen sich für einmalige Migrationen, den Zugriff von Auftragnehmern und alles, was man sonst nicht vergessen dürfte, zu widerrufen.

Schlüssel verwalten

Die API-Liste zeigt jeden Schlüssel des Kontos an: seinen Namen, eine gekürzte Schlüssel-ID, die Berechtigungsstufe, mit der er erstellt wurde, wann er zuletzt verwendet wurde, sowie seine IP-Einschränkung. Der letzte API-Aufruf wird in Ihrem Zeitzone des Kontos, und „Zulässige IP-Adressen“ lautet 0.0.0.0/0 wo es keine Einschränkung gibt.

Die Schlüssel-ID dient lediglich dazu, Schlüssel voneinander zu unterscheiden. Sie wird gekürzt und kann nicht zur Authentifizierung verwendet werden.

Die Berechtigungen werden bei der Erstellung festgelegt und können anschließend nicht mehr bearbeitet werden. Um die Funktionen eines Schlüssels zu ändern, erstellen Sie einen neuen Schlüssel mit den gewünschten Berechtigungen, wechseln Sie in Ihrer Integration zu diesem Schlüssel und löschen Sie anschließend den alten Schlüssel.

Das Drei-Punkte-Menü am Ende jeder Zeile enthält eine einzige Option: Löschen. Ein gelöschter Schlüssel funktioniert sofort nicht mehr, und Anfragen, die diesen Schlüssel verwenden, scheitern bei der Authentifizierung.

Verwendung des Schlüssels

Senden Sie den Schlüssel bei jeder Anfrage als Bearer-Token:

Anfrage

GET /v2/simcards HTTP/1.1
Host: api.simbase.com
Authorization: Bearer YOUR_API_KEY

Die vollständige Dokumentation zu den Endpunkten finden Sie unter developer.simbase.com.

Häufig gestellte Fragen

Verwandte Themen

• Webhooks — Lassen Sie sich Ereignisse an eine von Ihnen verwaltete URL senden, ohne die API abzufragen

• Usage Guard Toolkit (zum Selbermachen) — eine vorgefertigte Automatisierung, die einen API-Schlüssel mit Schreibberechtigung verwendet

• Diebstahlschutz — das simcards.details:write Anwendungsbereich in der Praxis

• Zeitzone des Kontos — Legt die Zeitzone fest, in der die Spalte „Letzter API-Aufruf“ angezeigt wird