Een API-sleutel verifieert je verzoeken aan de Simbase API. Elke sleutel bevat een reeks machtigingen die je bij het aanmaken ervan hebt gekozen, en die machtigingen liggen vanaf dat moment vast. Eén sleutel kan voor meerdere integraties worden gebruikt, maar één sleutel per integratie is de veiligere opzet. Sleutels worden aangemaakt en beheerd in het dashboard, onder Integraties → API.

Maak een API-sleutel aan

1. Log in om dashboard.simbase.com.

2. Ga naar Integraties → API.

3. Klik op ‘Nieuwe API-sleutel aanmaken’.

4. Geef de sleutel een naam die aangeeft waarvoor hij dient, bijvoorbeeld Usage Guard Toolkit. De naam is slechts een label. Deze verschijnt alleen in je sleutellijst en nergens anders.

5. Stel onder ‘Bronnen’ de machtigingen in die de sleutel nodig heeft. Zie Rechten hieronder.

6. Klik op ‘API-sleutel aanmaken’ en kopieer vervolgens de sleutel.

Bekijk de onderstaande demo voor stapsgewijze instructies:

Rechten

Toegangsrechten worden per bron ingesteld, op een van de drie niveaus. Geen betekent dat de sleutel die bron helemaal niet mag raken, en dit is de standaardinstelling voor elke rij. Lees haalt gegevens op en brengt geen wijzigingen aan. Schrijf maakt aan, werkt bij en verwijdert; als je deze optie selecteert, wordt ook ‘Lezen’ in dezelfde rij geselecteerd, omdat alles wat schrijft eerst moet lezen.

Niet elke bron biedt alle drie de opties. ‘Account’ en ‘Gebruik’ zijn alleen-lezen, dus daar wordt ‘Geen’ en ‘Lezen’ weergegeven. ‘SIM-kaartstatus’, ‘Resetten’, ‘Registratie’ en ‘Automatisch uitschakelen’ zijn acties in plaats van gegevens, dus daar wordt ‘Geen’ en ‘Schrijven’ weergegeven.

De bronnenboom

Ouder- en kindrijen

Naast de namen van ‘SIM-kaarten’, ‘Hulpprogramma’s’ en ‘Integraties’ staat telkens een pijltje. Klik erop om de bijbehorende individuele machtigingen uit te vouwen.

• Als je een bovenliggend item instelt, worden alle onderliggende items op hetzelfde niveau ingesteld, of op het hoogste niveau dat het betreffende onderliggende item ondersteunt. Als je voor alle bronnen de instelling ‘Schrijven’ kiest, krijgen ‘Account’ en ‘Gebruik’ de instelling ‘Lezen’, omdat ‘Lezen’ het hoogste niveau is dat zij ondersteunen.

• Als je een kind-element op zichzelf zet, wordt bij het bovenliggende element niets geselecteerd weergegeven. Dat is de bedoeling. Een bovenliggend element geeft alleen een niveau weer als al zijn onderliggende elementen daarmee overeenkomen.

Een niveau kiezen

Zorg ervoor dat de integratie over het absolute minimum beschikt. Een sleutel die alleen gebruiksgegevens kan uitlezen, kan een simkaart niet uitschakelen als er gegevens uitlekken.

In de API-referentie worden deze weergegeven als scope-namen die zijn opgebouwd uit dezelfde boomstructuur. De gegevens van de simkaart worden gekoppeld aan simcards.details:read en simcards.details:schrijven.

Geavanceerde instellingen

Schakel ‘Geavanceerde instellingen weergeven’ in voor twee optionele velden. Beide velden mogen leeg blijven.

IP-beperkingen

Beperkt de sleutel tot één vertrouwd IP-adres of een reeks in CIDR-notatie. Verzoeken vanaf elk ander adres worden geweigerd. Laat het veld leeg als je geen beperking wilt instellen. De sleutellijst toont dan 0.0.0.0/0 onder ‘Toegestane IP-adressen’, wat betekent dat elk adres is toegestaan.

Verloopt over (aantal dagen)

Het aantal dagen vanaf de aanmaak totdat de sleutel niet meer werkt. Voer in 31 en de sleutel verloopt over 31 dagen. Laat het veld leeg en de sleutel verloopt nooit.

Tijdelijke sleutels zijn handig voor eenmalige migraties, toegang voor externe medewerkers en alles wat je anders zou moeten onthouden om in te trekken.

Beheer je sleutels

De API-lijst toont alle sleutels van het account: de naam, een ingekorte sleutel-ID, het machtigingsniveau waarmee de sleutel is aangemaakt, wanneer deze voor het laatst is gebruikt en de bijbehorende IP-beperking. De laatste API-aanroep wordt weergegeven in je tijdzone van het account, en het aantal toegestane IP-adressen bedraagt 0.0.0.0/0 waar geen beperking geldt.

De Key ID dient uitsluitend om sleutels van elkaar te onderscheiden. Deze wordt afgekort en kan niet worden gebruikt voor authenticatie.

Rechten worden bij het aanmaken vastgelegd en kunnen achteraf niet meer worden gewijzigd. Als je de mogelijkheden van een sleutel wilt aanpassen, maak dan een nieuwe sleutel aan met de gewenste rechten, schakel je integratie om en verwijder vervolgens de oude sleutel.

Het menu met drie puntjes aan het einde van elke rij bevat één optie: Verwijderen. Een verwijderde sleutel werkt onmiddellijk niet meer, en verzoeken waarbij deze sleutel wordt gebruikt, mislukken bij de authenticatie.

De toets gebruiken

Stuur de sleutel bij elk verzoek mee als een ‘bearer token’:

Verzoek

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

De volledige documentatie over eindpunten is te vinden op developer.simbase.com.

Veelgestelde vragen

Gerelateerd

• Webhooks — laat gebeurtenissen naar een door jou beheerde URL worden doorgestuurd, zonder de API te pollen

• Usage Guard Toolkit (Doe-het-zelf) — een kant-en-klare automatisering die gebruikmaakt van een API-sleutel met schrijfrechten

• Diefstalbeveiliging — de simcards.details:schrijven toepassingsgebied in de praktijk

• Tijdzone van het account — stelt de tijdzone in waarin de kolom ‘Laatste API-aanroep’ wordt weergegeven