Je diensten uitlezen en je DNS beheren via de API

Met een API-sleutel kan je eigen programma, script of koppeling gegevens bij ons ophalen zonder je inloggegevens. Naast je klanten en facturen kan dat ook voor je domeinen, hostingpakketten, servers, SSL-certificaten en abonnementen. En je kunt er de DNS-records van je domeinen mee toevoegen, aanpassen en verwijderen. Hoe je een sleutel maakt en beveiligt, lees je in Een API-sleutel aanmaken en beveiligen.

Wat kan er met de API?

• Domeinen: je domeinnamen met status, verloopdatum en nameservers.
• DNS: de DNS-records van je domeinen opvragen, en records toevoegen, aanpassen of verwijderen.
• Hosting: je hostingpakketten met status, looptijd en wat er in het pakket zit.
• VPS: je servers met status, specificaties, besturingssysteem en IP-adressen.
• SSL-certificaten: je los bestelde certificaten met status en verloopdatum.
• Abonnementen: wat je per maand, kwartaal of jaar betaalt, met de prijs en de volgende verlengdatum.

Bestellen, opzeggen of andere instellingen wijzigen kan via de API niet. Wachtwoorden, inloggegevens en sleutels van je diensten geeft de API nooit.

Welke bevoegdheden kies je?

Bij het aanmaken van een sleutel kies je bij Bevoegdheden wat de sleutel mag. Kies alleen wat je programma echt nodig heeft:

• Domeinen lezen, Hosting lezen, VPS lezen, SSL-certificaten lezen en Abonnementen lezen om die gegevens op te vragen.
• DNS lezen om de DNS-records van je domeinen op te vragen.
• DNS wijzigen om DNS-records toe te voegen, aan te passen en te verwijderen. Kies er meestal ook DNS lezen bij, dan kan je programma de bestaande records en hun id's opvragen.

Een sleutel kun je achteraf niet aanpassen. Wil je hem meer of minder laten doen, trek hem dan in en maak een nieuwe.

Een sleutel die je DNS mag wijzigen

1. Ga in je klantportaal naar API-sleutels. Je vindt die pagina onder Account in de zijbalk, en via je naam rechtsboven.
2. Vul bij Naam in waar de sleutel voor is, bijvoorbeeld "Certificaten webserver".
3. Zet bij Bevoegdheden een vinkje bij DNS wijzigen en bij DNS lezen.
4. Vul bij Toegestane IP-adressen het IP-adres in van de server of computer waarop je programma draait, één per regel. Bij een sleutel die mag wijzigen is dit verplicht.
5. Klik op Sleutel genereren en vul je wachtwoord in.
6. Kopieer de sleutel met Kopiëren en zet hem meteen in je programma. Je ziet hem maar één keer.

Waarom een vast IP-adres?

Met een sleutel die je DNS mag wijzigen, kan iemand je website of e-mail naar een andere server laten wijzen. Daarom werkt zo'n sleutel alleen vanaf de IP-adressen die je zelf hebt ingevuld. Komt de sleutel toch bij iemand anders terecht, dan heeft die er vanaf een ander adres niets aan. Verandert het adres van je server, voeg dan bij de sleutel het nieuwe adres toe met Toevoegen en haal daarna het oude weg. Het laatste adres van zo'n sleutel kun je niet weghalen. Trek de sleutel dan in en maak een nieuwe.

Waar je op moet letten bij DNS

• Het werkt alleen voor een actief domein waarvan de DNS via OneLite loopt, dus met de nameservers van OneLite.
• Er gelden dezelfde regels als bij DNS-beheer in het klantportaal. Wat daar niet mag, mag via de API ook niet. De nameservers van het domein zelf wijzig je bijvoorbeeld niet via een record.
• Na elke wijziging staat de vorige versie bij Eerdere versie terugzetten in het klantportaal. Gaat er iets mis, dan zet je daar de oude stand terug.
• Een wijziging staat meestal binnen een paar minuten op de nameservers.

Een certificaat aanvragen via DNS

Het meest gebruikte voorbeeld is een certificaat dat via DNS wordt gecontroleerd, zoals een wildcardcertificaat van Let's Encrypt. Je programma zet dan tijdelijk een TXT-record op _acme-challenge, wacht tot de controle klaar is en haalt het record daarna weer weg. Veel certificaatprogramma's kunnen dat zelf als je ze de sleutel geeft. Een voorbeeld staat op de pagina API-documentatie in het klantportaal.

Alle aanroepen op een rij

Op de pagina API-sleutels klik je op API-documentatie voor een uitleg met voorbeelden. Met Alle endpoints uitproberen open je de naslag op onelite.nl/docs/api. Daar staan alle aanroepen met hun velden en foutmeldingen, en kun je ze met je eigen sleutel uitproberen. Let op: een wijziging die je daar uitprobeert, wordt echt doorgevoerd.

Bij elke sleutel zie je met Aanroepen welke aanroepen er de afgelopen 90 dagen mee zijn gedaan.