Een API-sleutel aanmaken

Voor: bestuurders · Schermen: Instellingen

Doel

Een koppeling zonder browser toegang geven: je boekhouding, een script dat gegevens inlaadt, een nieuwsbrief. Een sleutel werkt als een eigen account met de rechten die je kiest, enkel voor jouw coöperatie; in de audit-trail staat de naam van de sleutel bij elke wijziging. Een sleutel heeft zelf geen tweede stap: geef hem enkel de rechten die de koppeling nodig heeft en laat hem niet langer leven dan nodig.

Konsono heeft nog geen publieke API-referentie; die volgt later.

Vooraf

• Je bent bestuurder en je tweede stap is bij de hand: een sleutel aanmaken vraagt hem altijd opnieuw.
• Je weet voor welke koppeling de sleutel dient en wie hem krijgt. Geef hem door via een veilige weg (een kluis voor wachtwoorden of geheimen), nooit per gewone mail of chat.

Stappen

1. Open Instellingen en kies API-sleutels. Staat API-sleutels toelaten uit, dan werkt geen enkele sleutel: zet de schakelaar aan.
2. Kies Sleutel aanmaken.
3. Geef de Naam (waarvoor de sleutel dient, bijvoorbeeld "Boekhouding"), kies de Rechten, tot wanneer hij geldt en eventueel de adressen waarvandaan hij mag komen. Kies Sleutel aanmaken.
4. De app vraagt je tweede factor opnieuw: "Bevestig met je tweede factor". Kies Bevestigen en verdergaan. Je meldt opnieuw aan en komt terug in dit venster; wat je invulde, blijft bewaard.
5. Kies opnieuw Sleutel aanmaken.
6. De app toont de sleutel één keer. Kies Sleutel kopiëren, bewaar hem veilig en kies Ik heb hem bewaard. Kwijt is een nieuwe sleutel maken. Op de afbeelding is de sleutel bewust afgedekt.
7. De sleutel staat in de lijst met zijn begin, de rechten, de datum waarop hij vervalt en wanneer hij laatst gebruikt werd.

Velden

Veld	Verplicht	Uitleg
Naam	ja	Waarvoor de sleutel dient, bijvoorbeeld "Boekhouding" of "Mailchimp-sync". Eén sleutel per koppeling.
Rechten	ja	Lezen (aanbevolen): vennoten, aandelensoorten, journaal en documenten lezen. Lezen en schrijven: ook vennoten, instellingen en aandelensoorten wijzigen, geen boekingen. Lezen, schrijven en boeken: ook het journaal boeken (intekeningen, overdrachten, uittredingen en een import), enkel als de koppeling dat echt moet.
Geldig tot en met	ja	Standaard 90 dagen, hoogstens 365 dagen. Maak tijdig een nieuwe sleutel; twee sleutels tegelijk kan, zodat je kunt wisselen zonder onderbreking.
Enkel vanaf deze adressen	nee	IP-adressen of netwerken (CIDR), één per lijn. Voor een koppeling vanaf een vaste server is dit de beste bescherming. Leeg: vanaf elk adres.

Daarna

• Alle bestuurders krijgen een mail als een sleutel aangemaakt of ingetrokken wordt, en twee weken voor hij vervalt.
• De koppeling stuurt de sleutel mee in de header Authorization: Bearer <sleutel>, nooit in een adres, en enkel op de routes van jouw coöperatie.
• Intrekken werkt meteen en kan niet ongedaan gemaakt worden; de sleutel blijft in de lijst staan. Wat een sleutel nooit kan, staat hieronder.

Goed om te weten

• Zet API-sleutels toelaten uit bij twijfel over een lek: dan werkt geen enkele sleutel.
• Wisselen zonder onderbreking: maak een nieuwe sleutel, laat de koppeling overschakelen en trek dan de oude in.
• In de lijst zie je ook vanaf welk adres een sleutel laatst gebruikt werd.
• Een sleutel kan nooit rijksregisternummers lezen of schrijven, geen gebruikers beheren, geen sleutels maken en geen volledige export nemen.