API-endepunkter

Referanse for Lumi API-endepunktene.

Innsending (API-nøkkel)

Primær integrasjonsmetode for enterprise/BYOC-kunder. Widgeten sender svar direkte fra nettleseren.

Endepunkt	Metode	Auth	Beskrivelse
`/api/v1/submission`	`POST`	`X-Api-Key: lumi_pk_...`	Send inn survey-svar
`/api/v1/submission`	`OPTIONS`	Ingen	CORS preflight

Headers

http

POST /api/v1/submission
Content-Type: application/json
X-Api-Key: lumi_pk_live_...

Eksempel

Innsending krever schemaVersion: 2 og en definition-blokk som beskriver survey-strukturen. Første gang et gitt surveyId sendes inn, registreres definisjonen i survey_definitions; etterfølgende innsendinger valideres mot den lagrede definisjonen. Strukturelle endringer (felt lagt til/fjernet/flyttet, fieldType endret, ratingVariant endret, option-id-er endret eller flyttet) krever en ny surveyId — API-et returnerer 409 definition_conflict med diff. Responsen beholder rå surveyId for bakoverkompatibilitet, men surveyIdRef er logg-sikker. Diffen kan inneholde redigerte identifikatorer og diffRedacted: true dersom felt- eller option-id-er matcher PII-mønstre. Se Datakontrakt for feltsemantikk.

curl -X POST https://lumi.din-bedrift.no/api/v1/submission \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: lumi_pk_live_..." \
  -d '{
    "schemaVersion": 2,
    "surveyId": "min-app-tilbakemelding",
    "surveyType": "rating",
    "submittedAt": "2026-03-29T12:00:00Z",
    "answers": [
      {
        "fieldId": "rating",
        "fieldType": "RATING",
        "question": { "label": "Hvor fornøyd er du?" },
        "value": { "type": "rating", "rating": 4, "ratingVariant": "emoji", "ratingScale": 5 }
      }
    ],
    "definition": {
      "surveyType": "rating",
      "fields": [
        { "fieldId": "rating", "fieldType": "RATING", "label": "Hvor fornøyd er du?", "ratingVariant": "emoji", "ratingScale": 5 }
      ]
    }
  }'

CORS

Endepunktet returnerer Access-Control-Allow-Origin: * for at nettleseren skal kunne sende direkte. pk_-nøkler kan begrenses med allowedOrigins ved opprettelse.

Rate limiting

API-nøkler håndheves med rateLimit per nøkkel. Standard er 1000 req/min, og overskridelse returnerer 429 Too Many Requests med Retry-After.

API-nøkkeladministrasjon

Krever sk_-nøkkel (secret key). Brukes for å opprette, liste, rotere og revokere nøkler.

Endepunkt	Metode	Beskrivelse
`/api/v1/admin/api-keys`	`POST`	Opprett ny nøkkel (pk eller sk)
`/api/v1/admin/api-keys`	`GET`	List nøkler for teamet
`/api/v1/admin/api-keys/{id}/rotate`	`POST`	Roter en nøkkel (med grace period)
`/api/v1/admin/api-keys/{id}`	`DELETE`	Revokere en nøkkel umiddelbart

Headers

http

Authorization: Bearer lumi_sk_live_...
Content-Type: application/json

Opprett nøkkel

curl -X POST https://lumi.din-bedrift.no/api/v1/admin/api-keys \
  -H "Authorization: Bearer lumi_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "keyType": "pk",
    "appName": "min-web-app",
    "allowedOrigins": ["https://app.din-bedrift.no"],
    "rateLimit": 1000
  }'

Respons (201 Created):

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "lumi_pk_live_...",
  "keyType": "pk",
  "team": "mitt-team",
  "appName": "min-web-app"
}

Roter nøkkel

curl -X POST https://lumi.din-bedrift.no/api/v1/admin/api-keys/{id}/rotate \
  -H "Authorization: Bearer lumi_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"gracePeriodHours": 72}'

Grace period (0-720 timer) lar den gamle nøkkelen fortsatt fungere mens du ruller ut den nye.

Revokere nøkkel

curl -X DELETE https://lumi.din-bedrift.no/api/v1/admin/api-keys/{id} \
  -H "Authorization: Bearer lumi_sk_live_..."

Organisasjonsadministrasjon

Krever OIDC-token fra en org-admin-bruker. Administrer organisasjon, team og OIDC-gruppekoblinger.

Endepunkt	Metode	Beskrivelse
`/api/v1/admin/org`	`GET`	Hent organisasjonsinfo
`/api/v1/admin/org/teams`	`GET`	List team i organisasjonen
`/api/v1/admin/org/teams`	`POST`	Opprett nytt team
`/api/v1/admin/org/teams/{slug}/group-mappings`	`POST`	Legg til OIDC-gruppekobling
`/api/v1/admin/org/teams/{slug}/group-mappings/{id}`	`DELETE`	Fjern OIDC-gruppekobling

Opprett team

curl -X POST https://lumi.din-bedrift.no/api/v1/admin/org/teams \
  -H "Authorization: Bearer <oidc-access-token>" \
  -H "Content-Type: application/json" \
  -d '{"slug": "produkt-team", "name": "Produktteamet"}'

Legg til OIDC-gruppekobling

Kobler en OIDC-gruppe (f.eks. Entra ID group ID) til et Lumi-team. Brukere i denne gruppen får tilgang til teamets data i dashboardet.

curl -X POST https://lumi.din-bedrift.no/api/v1/admin/org/teams/produkt-team/group-mappings \
  -H "Authorization: Bearer <oidc-access-token>" \
  -H "Content-Type: application/json" \
  -d '{"oidcGroupId": "550e8400-e29b-41d4-a716-446655440000"}'

For NAIS-kunder: TokenX / AzureAD-endepunkter

NAIS-native submission-endepunkter (/api/v1/nais/tokenx/submission, /api/v1/nais/azure/submission og de eldre /api/tokenx/v1/feedback / /api/azure/v1/feedback) er fjernet og returnerer 404. Bruk POST /api/v1/submission med en team-scoped API-nøkkel — lumi_sk_ via Authorization: Bearer for server-til-server (typisk fra en backend-proxy), eller lumi_pk_ via X-Api-Key for nettleser-bruk. Se Auth-konvensjoner for header-format.

En NAIS-spesifikk deployment-guide for API-nøkkel-pathen er planlagt. Ta kontakt på hei@lumianalytics.no hvis dette er kritisk for din NAIS-deployment.

Oppsett (onboarding)

Endepunkter for å sette opp Lumi første gang. Brukes av dashboard-veiviseren og kan også kalles direkte via CLI.

Endepunkt	Metode	Auth	Beskrivelse
`/api/v1/setup/status`	`GET`	OIDC Bearer	Sjekk om oppsett er gjort
`/api/v1/setup`	`POST`	OIDC Bearer (admin)	Opprett organisasjon (første gang)
`/api/v1/setup/keys`	`POST`	OIDC Bearer (admin)	Generer første nøkkelpar (sk + pk)

GET /api/v1/setup/status

Returnerer om en organisasjon allerede eksisterer. Krever OIDC Bearer-token.

curl https://lumi.din-bedrift.no/api/v1/setup/status \
  -H "Authorization: Bearer <jwt>"

Respons (200 OK) — ikke satt opp:

json

{
  "orgExists": false,
  "hasApiKeys": false,
  "orgName": null
}

Respons (200 OK) — allerede satt opp:

json

{
  "orgExists": true,
  "hasApiKeys": true,
  "orgName": "Din Bedrift AS"
}

POST /api/v1/setup

Oppretter organisasjon og default-team. Kan kun kalles én gang — returnerer 409 Conflict om organisasjon allerede eksisterer. Krever OIDC Bearer-token med admin-rolle.

curl -X POST https://lumi.din-bedrift.no/api/v1/setup \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Din Bedrift AS"
  }'

Respons (201 Created):

json

{
  "org": { "slug": "din-bedrift-as", "name": "Din Bedrift AS" },
  "team": { "slug": "default", "name": "Default" }
}

POST /api/v1/setup/keys

Genererer det første nøkkelparet (sk + pk) for default-teamet. Kalles som siste steg i oppsettsveiviseren. Krever OIDC Bearer-token med admin-rolle.

curl -X POST https://lumi.din-bedrift.no/api/v1/setup/keys \
  -H "Authorization: Bearer <jwt>"

Respons (201 Created):

json

{
  "secretKey": "lumi_sk_live_...",
  "publishableKey": "lumi_pk_live_..."
}

Lagre nøkkelen

Nøkkelen vises bare én gang. Lagre den sikkert — den trengs for all videre nøkkeladministrasjon.

Auth-konvensjoner

Klient	Header	Nøkkelformat	Brukstilfelle
Widget (nettleser)	`X-Api-Key: lumi_pk_...`	`pk_` (public key)	Sende inn survey-svar
Admin-klient (curl, CI)	`Authorization: Bearer lumi_sk_...`	`sk_` (secret key)	Team-scoped nøkkeladministrasjon og server-side innsending
Dashboard/org-admin	`Authorization: Bearer <jwt>`	OIDC JWT	Dashboard-tilgang og organisasjonsadministrasjon via OIDC-innlogging

Feilkoder

HTTP-statuskode	Årsak
`400 Bad Request`	Ugyldig forespørsel — manglende eller feil felter i request body
`401 Unauthorized`	Manglende eller ugyldig autentisering
`403 Forbidden`	Gyldig autentisering, men manglende tilgang (f.eks. feil origin eller team)
`409 Conflict`	Ressurs eksisterer allerede (f.eks. setup kalt to ganger)
`429 Too Many Requests`	Rate limit overskredet for nøkkelen

Se også

Datakontrakt — payload-struktur for innsending
Koble til backend — oppsett av integrasjon
Miljøer — URLer og deployment
Produksjonsherdning — origin-validering og nøkkelrotasjon

API-endepunkter ​

Innsending (API-nøkkel) ​

Headers ​

Eksempel ​

API-nøkkeladministrasjon ​

Headers ​

Opprett nøkkel ​

Roter nøkkel ​

Revokere nøkkel ​

Organisasjonsadministrasjon ​

Opprett team ​

Legg til OIDC-gruppekobling ​

For NAIS-kunder: TokenX / AzureAD-endepunkter ​

Oppsett (onboarding) ​

GET /api/v1/setup/status ​

POST /api/v1/setup ​

POST /api/v1/setup/keys ​

Auth-konvensjoner ​

Feilkoder ​

Se også ​

API-endepunkter

Innsending (API-nøkkel)

Headers

Eksempel

API-nøkkeladministrasjon

Headers

Opprett nøkkel

Roter nøkkel

Revokere nøkkel

Organisasjonsadministrasjon

Opprett team

Legg til OIDC-gruppekobling

For NAIS-kunder: TokenX / AzureAD-endepunkter

Oppsett (onboarding)

GET /api/v1/setup/status

POST /api/v1/setup

POST /api/v1/setup/keys

Auth-konvensjoner

Feilkoder

Se også