API-toegang en sleutels

Soms wil je gegevens uit Memly ergens anders gebruiken. Je boekhouder wil je abonnementen inlezen, je websitebouwer wil je prijzen op je eigen site tonen, of je hebt een dashboard waarin je alles bij elkaar ziet. Daar is een API voor, en de sleutel die daarbij hoort maak je zelf aan.

Twee dingen vooraf, zodat je weet waar je aan begint. De API is alleen-lezen, dus een systeem dat hem gebruikt kan niets in je omgeving aanmaken of wijzigen. En een sleutel geeft altijd toegang tot jouw omgeving en nooit tot die van iemand anders, want de omgeving volgt uit de sleutel zelf.

Eerst aanzetten

API-toegang staat niet standaard aan. Wij zetten het aan als je erom vraagt, dus stuur een berichtje naar hallo@memly.nl met kort waarvoor je het wilt gebruiken.

Zodra het aan staat verschijnt er in je instellingen een nieuw onderdeel. Je vindt het onder Instellingen, in de groep Technisch, en het heet Ontwikkelaar. Staat het er niet, dan is de toegang nog niet aangezet.

Een sleutel aanmaken

Op die pagina staat rechtsboven de knop Nieuwe sleutel. Je vult twee dingen in.

Waar gebruik je hem voor. Geef de sleutel een naam die je over een half jaar nog begrijpt. Iets als “koppeling met onze boekhouding” of “website van Anne” werkt beter dan “sleutel 1”. Als je er ooit drie hebt, is dit het enige waaraan je ziet welke bij wat hoort.

Wat mag deze sleutel lezen. Hier kies je de rechten. Vink alleen aan wat de koppeling echt nodig heeft; daarover hieronder meer.

Klik daarna op Aanmaken. Je krijgt de sleutel één keer te zien, en dat is letterlijk bedoeld. Wij bewaren er alleen een versleutelde afdruk van, dus we kunnen hem later niet voor je opzoeken, ook niet als je erom vraagt. Kopieer hem meteen en zet hem op de plek waar hij hoort. Sluit je het venster zonder te kopiëren, dan is er niets ergs aan de hand, maar moet er wel een nieuwe komen.

De rechten begrijpen

Er zijn vier soorten gegevens die je los van elkaar kunt vrijgeven.

• Bestellingen, facturen en abonnementen lezen. Wat er verkocht is, wat er betaald is en wat er nog openstaat.
• Leden en hun toegang lezen. Wie er lid is, met naam en e-mailadres.
• Producten en prijzen lezen. Je aanbod, zoals het op je betaalpagina’s staat.
• Trainingen en voortgang van leden lezen. Welke trainingen er zijn en hoe ver je leden zijn.

Bij elke keuze staat of die persoonsgegevens bevat. Dat onderscheid is het belangrijkste dat je bij een sleutel moet afwegen. Producten en prijzen gaan over jouw aanbod en niet over mensen, dus die kun je met een gerust hart aan een websitebouwer geven. De andere drie gaan over je leden en je klanten, en daarvan blijf jij verantwoordelijk voor wat ermee gebeurt, ook als een ander ze inleest.

Kies daarom niet alles aan omdat het makkelijk is. Vraag degene die de koppeling bouwt wat hij nodig heeft, en vink dat aan.

De sleutel doorgeven

Bouw je de koppeling niet zelf, dan moet de sleutel naar iemand anders. Stuur hem niet in een gewone mail of een chatbericht, want daar blijft hij jaren staan en je hebt geen idee wie er nog bij dat postvak kan.

Beter is een wachtwoordmanager met een deelfunctie, of een dienst die een eenmalige link maakt die na het openen vervalt. Kan dat allemaal niet, maak dan een sleutel per persoon aan. Dan kun je die ene later intrekken zonder dat de rest stopt met werken.

Bijhouden of hij nog gebruikt wordt

In de lijst zie je per sleutel wanneer hij voor het laatst gebruikt is en hoeveel aanroepen er zijn geweest. Dat is nuttiger dan het lijkt.

Een sleutel die je vorig jaar maakte en die al maanden op “Nooit gebruikt” staat, is een sleutel waar niemand meer iets aan heeft. Zulke sleutels zijn precies de sleutels die je wilt intrekken, want ze werken nog wel gewoon.

Onder de lijst staat een blok Geschiedenis. Daar zie je wat er met je sleutels gebeurd is: aangemaakt, ingetrokken, rechten gewijzigd, met datum en door wie. De eigenaar en de beheerders krijgen daar ook een mail van, behalve degene die de handeling zelf deed. Je krijgt dus geen mail over je eigen klik, wel over die van een ander. Doet Memly iets namens jou, dan krijgen jullie allemaal bericht.

Rechten aanpassen of intrekken

Achter elke actieve sleutel staat een menuutje met twee mogelijkheden. Bij een sleutel die al ingetrokken is staat er niets meer, want daar valt niets meer aan te veranderen.

Rechten wijzigen verandert wat de sleutel mag lezen. Dat werkt meteen, dus het systeem dat hem gebruikt merkt het bij de eerstvolgende aanroep. Handig als een koppeling later iets extra’s nodig heeft, of juist minder.

Intrekken zet de sleutel definitief stil. Elk systeem dat hem gebruikt stopt op datzelfde moment met werken, dus doe het bewust. Terugdraaien kan niet; er moet dan een nieuwe sleutel komen. De ingetrokken sleutel blijft wel in je lijst staan, met de status Ingetrokken, zodat je later nog kunt zien dat hij bestaan heeft.

Twijfel je of een sleutel is uitgelekt, trek hem dan in en maak een nieuwe. Dat is een kwestie van een minuut en het is altijd de goede afweging.

Als er “Memly-beheer” bij staat

Bij een sleutel kan in de kolom Aangemaakt het label Memly-beheer staan. Dat betekent dat wij hem hebben aangemaakt, bijvoorbeeld omdat je ons had gevraagd een koppeling voor je in te richten.

Wij kunnen dat, en we vinden dat je dan hoort te zien dat we het gedaan hebben. Daarom staat het in de lijst, staat het in je geschiedenis, en krijg je er een mail over op het moment zelf. Zie je zo’n sleutel staan zonder dat je erom gevraagd hebt, laat het ons dan weten.

Als een sleutel niets doet

Werkt een koppeling niet terwijl de sleutel klopt, dan zijn er twee verklaringen die van buitenaf niet te zien zijn. Ze staan allebei als melding boven je sleutellijst.

De eerste is dat API-toegang voor je omgeving weer uit staat. De tweede is dat je omgeving zelf niet actief is. In beide gevallen weigert de API elke aanroep, ook met een geldige sleutel. Intrekken kan dan overigens wel gewoon, want dat moet je nooit hoeven uitstellen.

Voor degene die de koppeling bouwt

De technische kant staat op een eigen pagina: memly.nl/ontwikkelaars. Daar vind je het adres van de API, hoe de sleutel meegestuurd wordt, welke gegevens elk onderdeel teruggeeft en wat de foutmeldingen betekenen.

Die pagina komt rechtstreeks uit de API zelf, dus wat daar staat is altijd wat de API op dit moment doet.