App-API-sleutels

Een App-API-sleutel laat een eigen programma of script bij SamenstelFlow inloggen zonder dat er iemand achter het scherm zit. Denk aan een koppeling met je eigen dossiersysteem of een geplande taak die ’s nachts een export klaarzet. Werk je alleen via de browser, dan heb je geen sleutel nodig.

Een sleutel is persoonlijk: hij hoort bij jouw account en handelt namens jou. Wat de sleutel mag, is exact wat jouw rol in elk kantoor mag. Verandert je rol, dan verandert dat direct mee. Behandel de sleutel dus als een wachtwoord: niet in e-mail, niet in een gedeeld document, niet in code die je publiceert.

Waar je ze vindt

Klik op de avatar rechtsboven en kies Mijn profiel. Daar staan twee kaarten: API-sleutel aanmaken en Mijn API-sleutels. Je ziet en beheert alleen je eigen sleutels, nooit die van een collega.

Een sleutel aanmaken

1. Vul bij Naam in waar de sleutel voor is, bijvoorbeeld “CI-pipeline” of “koppeling dossiersysteem”. Die naam is het enige waaraan je de sleutel later herkent, dus kies hem beschrijvend.
2. Vul bij Vervaldatum de datum en tijd in waarop de sleutel moet vervallen. Een vervaldatum is verplicht. Kies er een die past bij het doel: liever kort en verlengen dan jarenlang open.
3. Klik op Aanmaken.

De sleutel wordt daarna precies één keer getoond. Kopieer hem meteen met de knop Kopiëren en zet hem in de plek waar je programma zijn geheimen bewaart. Zodra je op Sluiten klikt, is de sleutelwaarde niet meer op te halen: SamenstelFlow bewaart hem niet. Ben je hem toch kwijt, maak dan een nieuwe aan en verwijder de oude.

Je kunt maximaal 20 sleutels per vier uur aanmaken. Kom je daarboven, dan krijg je de melding “Te veel verzoeken. Probeer het later opnieuw.”

De sleutel gebruiken

Je programma stuurt de sleutel mee als HTTP-header x-api-key. Voor alles wat binnen een kantoor speelt, stuur je daarnaast de header X-Office-Id mee met het kantoor waarin de aanroep moet gebeuren. Wordt een sleutel niet herkend of is hij verlopen, dan volgt een 401-antwoord.

Na te veel mislukte pogingen achter elkaar wordt de bron tijdelijk geblokkeerd. Loop je daar tegenaan omdat een script met een oude sleutel bleef doorproberen, corrigeer dan eerst het script en neem contact op met support als de blokkade blijft.

Verlopen sleutels herkennen

De tabel Mijn API-sleutels toont per sleutel de Naam en de Vervaldatum. Is de datum verstreken, dan staat er rood (verlopen) achter. Een verlopen sleutel geeft geen toegang meer, maar blijft in de lijst staan tot je hem verwijdert.

Stopt een koppeling er ineens mee, kijk dan hier eerst: een verlopen sleutel is de meest voorkomende oorzaak. Maak een nieuwe sleutel aan, zet die in je programma en verwijder daarna de oude.

Een sleutel intrekken

Klik in de tabel op Verwijderen en bevestig. Toepassingen die deze sleutel gebruiken, krijgen direct geen toegang meer. De actie kan niet ongedaan worden gemaakt.

Trek een sleutel meteen in als je vermoedt dat hij is uitgelekt, of als de koppeling waarvoor hij is gemaakt niet meer bestaat.

Volgende stap

Wil je eerst zien wat SamenstelFlow oplevert, zonder eigen administratie? Kijk in het Demo Kantoor.