Spring til indhold

Grundfast

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

http
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:

http
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 aldrig token — dér gælder kun din session eller headeren.

Brug headeren, hvor du kan

En URL havner steder, en header ikke gør: i proxy- og serverlogs undervejs, i browserhistorik og i links, der deles. Vi logger aldrig query-strenge, og vores svar bærer 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_
DataDe rigtige registreDe samme rigtige registre
FaktureringTæller mod planens kvote; overforbrug faktureres på betalte planerFaktureres aldrig og tæller ikke mod planens forbrug
Månedligt loftPlanens kvote (se Rate limits)5.000 kald pr. måned, uanset plan
Burst pr. minutPlanens burst-grænseSamme burst-grænse som planen
Header på svaretX-Grundfast-Environment: liveX-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

  1. Log ind i dashboardet (opret en gratis konto, hvis du ikke har en).
  2. 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.
  3. 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

En hemmelig nøgle (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_ eller gf_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.

ScopeDækker
ejendomEjendomsprofil: alle registre for én ejendom i ét kald
adresseAdresser, postnumre, vejnavne, autocomplete og datavask
bbrBBR, bygningssøgning og bygningspolygoner
matrikelMatriklen, jordstykker og ejerlav
dagiAdministrative inddelinger (DAGI)
dhmHøjdemodellen (DHM)
stednavneStednavne
cvrCVR-virksomheder
energimaerkeEnergimærker
vurderingEjendomsvurderinger
planPlandata
miljoeJord, natur, byggelinjer, støj og miljøscreening
luftfotoLuftfoto (ortofoto)
eksportBulk-eksport og jobs (lister i baggrunden)
overvaagningEjendomsovervågning og adresseændringer
usageForbrug: læs kontoens forbrugsstatistik
webhooksWebhooks: 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.

POST /v1/keys — en nøgle, der kun kan slå adresser op
{ "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-* eller Cookie) eller et JSONP-callback, godkendes aldrig af en binding, men svarer 401 med koden ip_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:

RolleKan
EjerAlt, også team, betaling og sletning af kontoen. Der er altid mindst én ejer.
UdviklerOprette og tilbagekalde nøgler, IP-bindinger, webhooks, overvågning og eksporter.
ØkonomiPlan, betaling og fakturaer, og se forbrug og nøgler.
LæseadgangSe 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

StatusBetydningHvad du gør
401Nø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.
403Kontoen 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.
403En 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.
429For 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/totals og /v1/stats/top — Grundfasts egne optællinger af adresser, bygninger og jordstykker.
  • /openapi.json — OpenAPI 3.1-specifikationen for hele API’et.