# 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_`.

## 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](https://grundfast.dk/docs/mcp). 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_` |
| --- | --- | --- |
| 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](https://grundfast.dk/docs/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](https://grundfast.dk/docs/adressefelt#offentlige-noegler).

## Opret en nøgle

1. Log ind i [dashboardet](https://grundfast.dk/dashboard?mode=register) (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](https://grundfast.dk/docs/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](#offentlige-noegler).

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](https://grundfast.dk/dashboard/keys) → "Avanceret: hjemmeside-nøgle og adgang", og du skriver de websites, den må bruges fra. Den åbner kun adresseopslagene; se [offentlige nøgler](#offentlige-noegler).
- **Bare et adressefelt?** Så er [adressefelt-widgetten](https://grundfast.dk/docs/adressefelt) 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.

```json
{ "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](https://grundfast.dk/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](https://grundfast.dk/docs/fejl).

## 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](https://grundfast.dk/docs/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.

- Åbne endpoints: se https://grundfast.dk/docs/api
