Authenticatie
Bearer-token
Stuur Authorization: Bearer sk_live_… mee met elk verzoek. Zet een sleutel nooit in een URL of een cookie; er is geen andere header voor. Een ontbrekende, misvormde, ingetrokken of verlopen sleutel antwoordt 401 unauthorized, zonder te zeggen welke.
Een sleutel hoort bij één werkruimte. GET /v1/workspaces/current geeft die en het bijbehorende abonnement terug. Stuur je X-Workspace-Id mee, dan moet die de werkruimte van de sleutel noemen.
Sleutels maken
Maak sleutels in de app onder Settings → API. Editors, beheerders en de eigenaar maken sleutels die als henzelf handelen; beheerders kunnen ook die van anderen hernoemen en intrekken. Kijkers kunnen geen sleutels maken. Een werkruimte kan 50 actieve sleutels bevatten.
Het geheim wordt één keer getoond en wij bewaren alleen de hash. De API staat geen cross-origin browseraanroepen toe: houd sleutels op je server.
Scopes
Kies scopes bij het maken van de sleutel; ze kunnen achteraf niet worden gewijzigd (roteer of maak een nieuwe sleutel). Een verzoek heeft de scope van de route nodig, vermeld bij elke route in de API-referentie. Een sleutel zonder die scope krijgt 403 forbidden met details.reason missing_scope.
codes:readCodes, hun versies en activiteit ophalen en lezen; bestanden downloaden; exports en bulkruns starten en lezen.Viewer of hogercodes:writeCodes aanmaken, wijzigen, pauzeren, verplaatsen en verwijderen; bulk aanmaken; logo’s en bestanden uploaden.Editor of hogeranalytics:readAnalyse van de werkruimte en per code, en records per scan.Viewer of hogersubmissions:readAntwoorden op gehoste formulieren. Ze bevatten persoonsgegevens van respondenten.Editor of hogerfolders:readMappen ophalen en lezen.Viewer of hogerfolders:writeMappen aanmaken, hernoemen, verplaatsen en verwijderen. Delen blijft in de app.Editor of hogertemplates:readOntwerpsjablonen ophalen en lezen.Viewer of hogertemplates:writeOntwerpsjablonen aanmaken, wijzigen en verwijderen.Editor of hogerdomains:readEigen domeinen en hun status ophalen, om er een te kiezen voor nieuwe codes.Viewer of hogerwebhooks:readWebhook-endpoints en hun leveringen ophalen.Beheerder of hogerwebhooks:writeWebhook-endpoints registreren, wijzigen en verwijderen; een testevent sturen; opnieuw leveren. Alleen voor beheerders.Beheerder of hogertags:readTags van de werkruimte ophalen en hoeveel codes ze hebben.Viewer of hogertags:writeTags aanmaken, hernoemen, van kleur veranderen en verwijderen. Codes taggen vereist Codes · write.Editor of hogercards:readVisitekaartjes van het team en hun analyse ophalen en lezen.Viewer of hogercards:writeVisitekaartjes aanmaken, wijzigen, deactiveren en opnieuw toewijzen. Alleen voor beheerders.Beheerder of hogerconversions:writeConversies vanaf je server sturen (bestellingen, aanmeldingen) voor de scanfunnel.Editor of hogerRollen
Een sleutel doet nooit meer dan de huidige rol van de maker toestaat, begrensd op Editor. Wordt de maker teruggezet naar kijker, dan verliest de sleutel meteen zijn schrijfscopes; verlaat de maker de werkruimte, dan worden zijn sleutels ingetrokken.
webhooks:read en webhooks:write zijn de uitzondering: alleen beheerders en de eigenaar kunnen ze verlenen, en ze blijven alleen werken zolang de maker nog beheerder is.
Map- en IP-beperkingen
Een sleutel kan worden beperkt tot maximaal 20 mappen en hun submappen, bijvoorbeeld één sleutel per klantmap. Hij ziet dan niets daarbuiten, en een schrijfactie elders antwoordt 403 met details.reason api_key_folder_restricted.
Een sleutel kan ook worden beperkt tot maximaal 20 IP-bereiken in CIDR-vorm (203.0.113.0/24). Een aanroep van elders antwoordt 403 met details.reason ip_not_allowed.
Verlopen en roteren
Een sleutel kan verlopen op een datum die je kiest. Een sleutel roteren geeft een nieuw geheim uit met dezelfde naam, scopes en beperkingen; het oude geheim blijft standaard 24 uur werken (0 tot 168), zodat je het nieuwe zonder downtime kunt uitrollen. Intrekken werkt direct.
Wat een sleutel niet kan
Sleutels roepen alleen de routes uit de API-referentie aan. Je account, leden en uitnodigingen, facturatie, werkruimte-instellingen, delen, domeininrichting en de API-sleutels zelf blijven in de app: die routes antwoorden een sleutel met 403 forbidden en details.reason session_required.