API-sleutels beheren
Een API-sleutel aanmaken, wijzigen en intrekken zodat een externe koppeling NOCCIE kan gebruiken
Met een API-sleutel kan externe software gegevens uit NOCCIE ophalen, zonder dat iemand hoeft in te loggen. Denk aan een website die jouw producten toont, of een koppeling die je zelf laat bouwen.
Wat is een API-sleutel?
Een API-sleutel bestaat uit twee delen:
- Een sleutel-id (in NOCCIE: Sleutel-ID). Dit is de naam van de sleutel. Het begint met
tk_en is niet geheim. - Een geheim (in NOCCIE: Geheime sleutel). Dit werkt als een wachtwoord. Je ziet het maar één keer, direct nadat je de sleutel hebt aangemaakt.
Een sleutel hoort bij jouw organisatie in NOCCIE, niet bij een persoon. Hij werkt alleen binnen jouw organisatie en alleen voor de rechten die je hem geeft. Rechten bepalen wat de koppeling mag doen, zoals gegevens bekijken.
Heb je zelf een sleutel nodig?
Je hebt alleen een sleutel nodig als er software met NOCCIE moet praten. Gebruik je NOCCIE alleen zelf, dan hoef je hier niets mee. Laat je een koppeling bouwen? Geef je ontwikkelaar dan het sleutel-id en het geheim, en verwijs naar de technische API-documentatie.
Wie mag sleutels beheren?
Alleen medewerkers met de permissie API-sleutels beheren kunnen sleutels aanmaken, wijzigen en intrekken.
Heeft jouw rol deze permissie niet? Vraag dan een beheerder om hem toe te voegen. Je kunt een sleutel nooit meer rechten geven dan jijzelf hebt.
Een sleutel aanmaken
Kies in het menu van de instellingen voor API-sleutels. Dit menu-item zie je alleen met de permissie API-sleutels beheren. Kies daarna Nieuwe sleutel.
Geef de sleutel een naam
Kies een naam waaraan je later ziet waar de sleutel voor is, bijvoorbeeld de naam van de koppeling of de website. Je kunt maximaal 100 tekens gebruiken.
Kies de rechten
Vink aan wat de sleutel mag doen. Geef alleen de rechten die de koppeling echt nodig heeft. Je kunt alleen rechten kiezen die jijzelf ook hebt.
Op dit moment kan een sleutel alleen producten bekijken. Je kunt er dus geen gegevens mee aanpassen.
Stel eventueel een vervaldatum in
Heeft de sleutel maar tijdelijk toegang nodig? Vul dan bij Vervaldatum (optioneel) een datum in de toekomst in. Vanaf die datum werkt de sleutel niet meer en krijgt hij de status Verlopen. Laat je het veld leeg, dan blijft de sleutel werken tot je hem intrekt.
Bewaar het geheim
Kies Aanmaken. NOCCIE toont dan het sleutel-id en de geheime sleutel. Ook het tenant-id staat erbij: dat heeft de koppeling nodig in het pad van elke aanroep. Het tenant-id is niet geheim.
Het geheim zie je maar één keer
Kopieer het geheim meteen met Kopieer en bewaar het op een veilige plek, bijvoorbeeld in een wachtwoordmanager. Heb je het scherm gesloten zonder te kopiëren? Dan kun je het geheim niet meer opvragen. Maak in dat geval een nieuwe sleutel aan en trek de oude in.
Een sleutel wijzigen
Kies bij een bestaande sleutel Wijzigen. Je kunt de naam, de rechten en de vervaldatum aanpassen. Sla de wijzigingen op met Opslaan. Het geheim blijft hetzelfde.
- Een wijziging in de rechten werkt direct. De koppeling hoeft niet opnieuw in te loggen en heeft geen nieuwe sleutel nodig.
- Je kunt een sleutel alleen rechten geven die jijzelf ook hebt.
- Je haalt een vervaldatum weg door het veld leeg te maken.
- Een ingetrokken sleutel kun je niet meer wijzigen.
Een sleutel intrekken
Trek een sleutel in als je hem niet meer gebruikt, of als je denkt dat iemand anders het geheim kent. Kies bij de sleutel Intrekken en bevestig dit.
De sleutel werkt vanaf dat moment niet meer. Dat geldt ook voor toegang die de koppeling al had opgehaald. Intrekken kun je niet ongedaan maken. Heb je de sleutel toch weer nodig, maak dan een nieuwe aan.
Een sleutel vervangen
Wil je een sleutel regelmatig verversen? Doe dat in deze volgorde:
- Maak een nieuwe sleutel aan met dezelfde rechten.
- Zet de nieuwe sleutel in de koppeling en controleer of alles werkt.
- Trek de oude sleutel in.
Wat gebeurt er als een medewerker vertrekt?
Niets. De sleutel hoort bij je organisatie, niet bij degene die hem heeft aangemaakt. De koppeling blijft dus gewoon werken als die medewerker weggaat of zijn account verdwijnt.
Kende de medewerker het geheim, of vertrouw je de situatie niet? Trek de sleutel dan in en maak een nieuwe aan.
Activiteit en geschiedenis
Bij elke sleutel legt NOCCIE vast wat er is gebeurd: wie het deed, wanneer en wat er veranderde. Dat geldt voor aanmaken, hernoemen, wijzigen van de rechten, wijzigen van de vervaldatum en intrekken. Je ziet ook wanneer de sleutel voor het laatst is gebruikt, zodat je ongebruikte sleutels herkent. Dat is bij benadering het laatste moment waarop de koppeling met deze sleutel om toegang heeft gevraagd, met een nauwkeurigheid van ongeveer vijf minuten. Aanvragen die de koppeling doet met toegang die al is verleend, werken dit tijdstip niet bij. Het is dus niet het tijdstip van elke afzonderlijke aanvraag.
Het geheim zelf staat nooit in de geschiedenis.
Veilig omgaan met sleutels
- Deel een sleutel nooit via e-mail, chat of een document dat anderen kunnen lezen.
- Maak voor elke koppeling een eigen sleutel. Dan kun je er één intrekken zonder de rest te storen.
- Geef elke sleutel alleen de rechten die nodig zijn.
- Stel een vervaldatum in als de toegang tijdelijk is.
- Controleer af en toe de lijst met sleutels en trek de sleutels in die je niet meer gebruikt.
- Geef de sleutel alleen aan degene die de koppeling bouwt of beheert, en laat hem niet in een website of app terechtkomen. Je ontwikkelaar of leverancier weet hoe hij hem veilig opslaat.
Veelgestelde fouten
Ik zie het geheim niet meer
Het geheim wordt maar één keer getoond. Maak een nieuwe sleutel aan, zet die in de koppeling en trek de oude sleutel in.
De koppeling krijgt een foutmelding dat de sleutel niet klopt
Controleer of het sleutel-id en het geheim goed zijn overgenomen, zonder extra spaties. Kijk daarna of de sleutel niet is ingetrokken en of de vervaldatum nog niet is verstreken. Een sleutel die niet bestaat, een verkeerd geheim, een ingetrokken sleutel en een verlopen sleutel geven dezelfde melding. Een sleutel-id met een verkeerd teken, zoals een spatie, geeft een melding dat de aanvraag ongeldig is.
De koppeling krijgt een melding dat iets niet is toegestaan
De sleutel heeft het recht voor die actie niet, of de actie is nog niet beschikbaar voor API-sleutels. Ontbreekt het recht? Pas dan de rechten van de sleutel aan.
Ik kan een bepaald recht niet kiezen
Je kunt alleen rechten kiezen die jijzelf ook hebt. Sommige gevoelige rechten, zoals het beheren van facturatie, het abonnement of de sleutels zelf, kun je nooit aan een sleutel geven.
Ik kan geen sleutels beheren
Je mist de permissie API-sleutels beheren. Vraag een beheerder om die aan je rol toe te voegen.
Laatst bijgewerkt op 8 oktober 2026