Godkendelse og nøgler
Alle data-endpoints kræver en API-nøgle i Authorization-headeren (eller som ?token=, hvor en header ikke kan sættes). De hemmelige nøgler findes i to slags: gf_live_ til produktion og gf_test_ til udvikling og CI. Til adressefelter i browseren er der desuden offentlige nøgler, gf_pub_.
På denne side· 13 afsnit
- Send nøglen som Bearer-token
- Nøglen som ?token= — når du ikke kan sætte en header
- Live- og testnøgler
- Offentlige nøgler til browseren
- Opret en nøgle
- Tilbagekald en nøgle
- Hold nøglen på serveren
- CORS-fejl, når du kalder fra en browser
- Begræns en nøgle med scopes
- Kald uden nøgle fra en fast IP-adresse
- Flere personer på kontoen
- 401 og 403
- Endpoints uden nøgle
Send nøglen som Bearer-token
GET /v1/bbr/ejendom/5651067 HTTP/1.1
Host: api.grundfast.dk
Authorization: Bearer gf_live_...Headeren er den form, du skal bruge, når du kan. Den gælder alle data-endpoints og MCP-serveren. Andre header-navne som X-API-Key eller apikey læses ikke: kaldet får 401 med code: "api_key_wrong_header" og et hint, der viser den rigtige form.
Nøglen som ?token= — når du ikke kan sætte en header
Nogle systemer kan kun tage en URL: GIS-programmer, regnearks-webforespørgsler, en <img>- eller kortflise-URL og visse low-code-forbindelser. Til dem accepterer data-endpoints under /v1/* og /mcp nøglen som query-parameteret token:
GET /v1/adgangsadresser?postnr=8000&token=gf_live_... HTTP/1.1
Host: api.grundfast.dk- Kaldet måles, begrænses og faktureres præcis som med headeren — det er den samme nøgle.
- Sender du både header og
token, gælder headeren. - Dashboardet og konto-endpoints (nøgler, betaling, eksport,
/v1/me) tager aldrigtoken— dér gælder kun din session eller headeren.
Brug headeren, hvor du kan
Referrer-Policy: no-referrer, men mellemled, du ikke kontrollerer, kan gemme URL’en. Giv en token-URL sin egen nøgle, så du kan tilbagekalde netop den, hvis den slipper ud.Live- og testnøgler
gf_live_ | gf_test_ | |
|---|---|---|
| Data | De rigtige registre | De samme rigtige registre |
| Fakturering | Tæller mod planens kvote; overforbrug faktureres på betalte planer | Faktureres aldrig og tæller ikke mod planens forbrug |
| Månedligt loft | Planens kvote (se Rate limits) | 5.000 kald pr. måned, uanset plan |
| Burst pr. minut | Planens burst-grænse | Samme burst-grænse som planen |
| Header på svaret | X-Grundfast-Environment: live | X-Grundfast-Environment: test |
Alle nøgler, også testnøgler, kræver en bekræftet e-mail på kontoen. Brug en testnøgle i CI, staging og under udvikling. Ved sandbox-loftet svarer API’et 429 med beskeden, at du skal bruge en live-nøgle i produktion; X-Quota-*-headerne viser sandbox-loftet og nulstilles den 1. i måneden (UTC).
Offentlige nøgler til browseren
Til et adressefelt i en webshop findes en tredje slags: den offentlige nøgle, gf_pub_live_ eller gf_pub_test_. Den må stå i en webside, fordi den kun virker fra de domæner, du har skrevet på den, kun åbner adresseopslag (søgning, autocomplete, én adresse, datavask og postnumre) og har en ekstra grænse pr. IP-adresse. Den måles og faktureres som andre nøgler. Se Adressefelt.
Opret en nøgle
- Log ind i dashboardet (opret en gratis konto, hvis du ikke har en).
- Gå til Nøgler, giv nøglen et navn og vælg live eller test — og hemmelig eller offentlig. En offentlig nøgle skal have mindst ét domæne.
- Kopiér nøglen med det samme. Den vises kun én gang — vi gemmer kun en hash af den og kan ikke vise den igen.
Nøgler oprettes og tilbagekaldes med din dashboard-session; en API-nøgle kan ikke oprette flere nøgler. Ingen nøgle, heller ikke en testnøgle, kan oprettes, før kontoens e-mailadresse er bekræftet.
Nøgler fra dashboardet har rettigheden read_only. Alle data-endpoints er læsninger, så den dækker hele API’et.
Tilbagekald en nøgle
Tilbagekald én nøgle ad gangen under Nøgler i dashboardet, eller brug Tilbagekald alle nøgler, hvis du har mistanke om, at en nøgle er lækket. En tilbagekaldt nøgle afvises med 401; ændringen slår igennem inden for få sekunder.
Har du abonneret på webhooks, udsendes key.created og key.revoked, når nøgler oprettes og tilbagekaldes.
Hold nøglen på serveren
Aldrig i browserkode
gf_live_, gf_test_) i frontend-kode, en mobilapp eller et offentligt repository kan læses af alle. Kald Grundfast fra din egen backend og send kun resultatet videre til klienten. Læg nøglen i en miljøvariabel eller en secret manager. Skal browseren selv slå adresser op, så brug en offentlig nøgle.Et typisk mønster er et lille endpoint i din egen backend, der slår op hos Grundfast og returnerer netop de felter, din frontend skal bruge. Så styrer du samtidig, hvor mange kald brugerne kan udløse.
CORS-fejl, når du kalder fra en browser
Kalder du API’et med en hemmelig nøgle fra JavaScript på dit eget website, stopper browseren kaldet med en CORS-fejl ("blocked by CORS policy"). Det er med vilje, og vi åbner ikke for det: en nøgle i browserkode kan læses og misbruges af alle, der besøger siden.
- Kald API’et fra din server. Din backend slår op hos Grundfast med nøglen og sender kun svaret videre til siden. Server-til-server-kald har ingen CORS.
- Browserkald kræver en offentlig nøgle (
gf_pub_live_ellergf_pub_test_). Den opretter du under API-nøgler → "Avanceret: hjemmeside-nøgle og adgang", og du skriver de websites, den må bruges fra. Den åbner kun adresseopslagene; se offentlige nøgler. - Bare et adressefelt? Så er adressefelt-widgetten den korteste vej — den bruger en offentlig nøgle og kræver ingen kode ud over ét script-tag.
Åbner du det afviste kald i browserens netværksfane, står årsagen i svaret: 403 med code: "secret_key_in_browser" og en hint, der siger det samme som her.
Begræns en nøgle med scopes
En nøgle kan begrænses til de områder, den skal bruge. Uden scopes når den alle data-endpoints, som nøgler altid har gjort. Med en liste når den kun de områder, listen nævner, og får 403 med type: "key_scope" alle andre steder — også i MCP-værktøjerne.
| Scope | Dækker |
|---|---|
| ejendom | Ejendomsprofil: alle registre for én ejendom i ét kald |
| adresse | Adresser, postnumre, vejnavne, autocomplete og datavask |
| bbr | BBR, bygningssøgning og bygningspolygoner |
| matrikel | Matriklen, jordstykker og ejerlav |
| dagi | Administrative inddelinger (DAGI) |
| dhm | Højdemodellen (DHM) |
| stednavne | Stednavne |
| cvr | CVR-virksomheder |
| energimaerke | Energimærker |
| vurdering | Ejendomsvurderinger |
| plan | Plandata |
| miljoe | Jord, natur, byggelinjer, støj og miljøscreening |
| luftfoto | Luftfoto (ortofoto) |
| eksport | Bulk-eksport og jobs (lister i baggrunden) |
| overvaagning | Ejendomsovervågning og adresseændringer |
| usage | Forbrug: læs kontoens forbrugsstatistik |
| webhooks | Webhooks: læs kontoens webhooks og leveringer, og send leveringer igen |
Den DAWA-kompatible flade under /dawa følger de samme scopes som registrene bag den: adresser, veje, postnumre, replikering og /dawa/reverse kræver adresse; kommuner, regioner og de andre inddelinger (også supplerendebynavne2) kræver dagi; ejerlav og jordstykker kræver matrikel; bebyggelser kræver stednavne. include=bbr læser BBR og kræver derfor også bbr.
usage og webhooks er konto-scopes: de giver en nøgle adgang til kontoens forbrug (/v1/me/usage/*, undtagen fejloversigten /v1/me/usage/errors, som kun dashboardet læser) og til webhooks — oversigten, leveringerne og genlevering — og ingen nøgle har dem, medmindre de er valgt. Sæt scopes, når nøglen oprettes, eller ret dem senere med PATCH /v1/keys/:id — ændringen gælder fra nøglens næste kald.
{ "name": "webshop", "mode": "live", "scopes": ["adresse"] }Kald uden nøgle fra en fast IP-adresse
Nogle systemer kan ikke sende en header eller gemme en hemmelighed — et ERP-udtræk, et batchjob bag en firewall. Bind i stedet serverens faste IP-adresse til en af dine nøgler under Nøgler → IP-binding i dashboardet. Kald fra den adresse uden nøgle bliver så godkendt, målt, begrænset og faktureret som den nøgle, og svaret bærer X-Grundfast-Auth: ip-binding.
- Bindingen venter, til nøglen selv har kaldt fra adressen. Først når den valgte nøgle har lavet ét kald fra IP-adressen, bliver bindingen aktiv. Det beviser, at du har adgang til adressen, så ingen kan binde en andens IP til deres konto.
- En aktiv binding kan ikke ændres. Vil du skifte adresse eller nøgle, så slet bindingen og opret en ny. En IP-adresse kan kun være aktivt bundet til én nøgle.
- En sendt nøgle vinder altid. Kommer der en nøgle med, bruges den — og en forkert nøgle er stadig
401. - Kun server-til-server. Et kald uden nøgle, der bærer en browsers headere (
Origin,Sec-Fetch-*ellerCookie) eller et JSONP-callback, godkendes aldrig af en binding, men svarer401med kodenip_binding_browser. Bind derfor kun en servers egen faste udgående adresse — aldrig et kontors fælles NAT-adresse, som alle medarbejderes browsere deler. - Tilbagekalder du nøglen, slettes dens bindinger med det samme. Bindingen arver nøglens scopes.
- IP-binding er med fra Starter, og antallet er begrænset pr. plan (se priser).
Flere personer på kontoen
En ejer kan invitere kolleger under Team i dashboardet. Den inviterede får en mail med et link, vælger en adgangskode og er derefter logget ind på den samme konto. Linket gælder i syv dage. Hver person har en rolle:
| Rolle | Kan |
|---|---|
| Ejer | Alt, også team, betaling og sletning af kontoen. Der er altid mindst én ejer. |
| Udvikler | Oprette og tilbagekalde nøgler, IP-bindinger, webhooks, overvågning og eksporter. |
| Økonomi | Plan, betaling og fakturaer, og se forbrug og nøgler. |
| Læseadgang | Se forbrug, nøgler, webhooks og team, men ikke ændre noget. |
En handling, rollen ikke må, giver 403 med type: "team_role". Antallet af pladser følger planen; ventende invitationer optager også en plads (402 med type: "seat_limit", når der ikke er flere). En login hører til én konto, så en adresse, der allerede har et Grundfast-login, kan ikke tage imod en invitation.
401 og 403
| Status | Betydning | Hvad du gør |
|---|---|---|
| 401 | Nøglen mangler (code: "api_key_missing"), er sendt i en forkert header (api_key_wrong_header), eller er ugyldig, udløbet eller tilbagekaldt. Svaret bærer et hint og en WWW-Authenticate-header, der beskriver det forventede format. | Tjek at headeren er Authorization: Bearer gf_... uden ekstra mellemrum eller anførselstegn. |
| 403 | Kontoen er suspenderet, nøglen er en administrationsnøgle, som ikke gælder for data-endpoints, eller nøglens scopes dækker ikke endpointet (type: "key_scope"). | Ret nøglens scopes i dashboardet, eller kontakt support. |
| 403 | En offentlig nøgle blev brugt fra et domæne, der ikke står på den, eller til et andet endpoint end adresseopslag. | Tilføj domænet under Nøgler, eller kald endpointet fra din server med en hemmelig nøgle. |
| 429 | For mange forsøg med ugyldige nøgler fra samme IP-adresse. Svaret bærer Retry-After. | Ret nøglen og vent det angivne antal sekunder. |
Fejl, der skyldes din plan frem for din nøgle, er 402 (funktionen kræver en højere plan) og 429 (kvote eller burst-grænse). Se Fejl og statuskoder.
Endpoints uden nøgle
Nogle endpoints kan kaldes uden nøgle. De er begrænset pr. IP-adresse og faktureres ikke:
/v1/demo/*— faste eksempler i samme form som de rigtige endpoints, fx/v1/demo/ejendom./v1/kodeliste/:navn— BBR-kodelisterne (se BBR)./v1/dagi— oversigten over DAGI-temaer./v1/stats/kommuner,/v1/stats/postnumre,/v1/stats/totalsog/v1/stats/top— Grundfasts egne optællinger af adresser, bygninger og jordstykker./openapi.json— OpenAPI 3.1-specifikationen for hele API’et.