API-sleutels

Een API-sleutel is hoe iets anders dan een mens met dit paneel praat: je facturatiepakket dat een account aanmaakt, een script dat 's nachts een backup controleert, een koppeling die DNS bijwerkt. Je maakt ze aan onder Platform → API-sleutels.

Alles op dit scherm draait om drie beslissingen die je één keer neemt en die daarna vastliggen: bij welke node-groep de sleutel hoort, welk niveau hij heeft, en welke scopes hij krijgt. Dit artikel gaat over die drie, en over wat er gebeurt als je een sleutel kwijtraakt.

De groep is de buitengrens

Een sleutel hoort bij precies één node-groep, en buiten die groep kan hij niets: niet lezen, niet wijzigen, en niet zien dát er iets bestaat. Noemt een verzoek met een sleutel van groep A een server, een account, een pakket, een login of een migratie uit groep B, dan komt er een 403 terug — vóórdat er ook maar één server gebeld is, en of het nu een leesverzoek was of een wijziging. Ook lijsten worden zo versmald: een sleutel ziet de rijen van een andere groep helemaal niet.

Die binding is later niet te wijzigen. Roteren behoudt hem; een sleutel voor een andere groep is een andere sleutel. Het formulier zegt dat vóórdat de sleutel bestaat, want dat is het enige moment waarop het je nog helpt.

Niveau en "handelt namens"

Naast de groep draagt een sleutel een niveau — beheerder, serverbeheerder, reseller of gebruiker. Een sleutel kan nooit meer dan dat niveau onder zijn eigen accounts mag. Dat is dezelfde controle die het paneel op een ingelogd persoon toepast, aan de serverkant, tegen dezelfde code.

Onder serverbeheerder hoort een sleutel bovendien bij één login: hij bereikt de accounts van díé login en die van niemand anders. Kies je een reseller, dan bereikt de sleutel diens klanten; kies je een gebruiker, dan alleen diens eigen hosting.

Scopes: lezen en wijzigen zijn twee dingen

Een sleutel krijgt scopes in de vorm familie:actie — bijvoorbeeld accounts:manage of dns:read. Een GET heeft :read nodig, alles wat iets verandert :manage. Let op: wijzigen impliceert lezen niet aan de serverkant. Het scherm vinkt lezen daarom automatisch mee aan als je wijzigen aanzet, zodat je er niet over hoeft na te denken; wie een sleutel met de opdrachtregel maakt, moet beide zelf geven.

De vakjes die je ziet komen van de server: alleen families die werkelijk routes hebben verschijnen. Een vakje dat niets zou verlenen kan dus niet bestaan, en een familie die er later bijkomt verschijnt vanzelf.

Het geheim zie je één keer

Bij aanmaken en bij roteren toont het paneel het geheim precies één keer. Daarna bewaart het alleen een hash: het kan het niet nog eens laten zien, ook niet aan jou, ook niet in het auditlogboek. Kwijt? Dan roteer je de sleutel. De groep, de scopes en het auditspoor blijven dan staan — alleen het geheim is nieuw, en het oude werkt onmiddellijk niet meer, zonder overgangsperiode.

De onthulkaart heeft een Tonen-knop en toont het geheim niet uit zichzelf, omdat een beheerpaneel vaak op een gedeeld scherm staat.

Snelheidslimiet, intrekken, en hoe je hem gebruikt

Elke sleutel heeft zijn eigen emmer: een aantal verzoeken per minuut plus een burst, allebei per sleutel in te stellen. Ga je eroverheen, dan volgt een 429 met een Retry-After-kop in seconden. Vraag om een hogere limiet in plaats van er tegenaan te blijven duwen.

Intrekken is definitief en kan niet ongedaan gemaakt worden; ingetrokken sleutels blijven in de lijst staan (zet Ingetrokken sleutels tonen aan) zodat het spoor leesbaar blijft.

# De sleutel als bearer-token; het voorvoegsel hoort erbij
curl -sS -H "Authorization: Bearer corecp_<prefix>_<geheim>" \
  https://paneel.voorbeeld.nl/api/v1/accounts

# Een wijziging is een taak. 200 = klaar binnen de wachttijd, 202 = nog bezig
curl -sS -X POST -H "Authorization: Bearer corecp_<prefix>_<geheim>" \
  -H "Content-Type: application/json" -d '{"domain":"voorbeeld.nl"}' \
  "https://paneel.voorbeeld.nl/api/v1/accounts/mijnaccount/domains?wait=45s"

Een fout komt altijd terug als {"error": {"code": …, "message": …}}. Vergelijk op code en nooit op de zin: de codes liggen vast, de zinnen niet.

Zie ook

• Koppelingen — de kant-en-klare koppelingen die zelf een sleutel meebrengen.
• Toegang tot een server — wat een mens mag, en waar dezelfde niveaus vandaan komen.
• Het auditlog controleren — waar het gebruik van een sleutel wordt vastgelegd.
• Instellingen van het platform — waar node-groepen worden beheerd.