API Adgangsvejledning

Digitalt Samtykke API - Digitaliseringsstyrelsen

API understøttelse for ekstern integration

Digitalt Samtykke API giver ekstern adgang til samtykkehåndtering under Digitaliseringsstyrelsen. Denne vejledning beskriver hvordan man opnår adgang via Fælleskommunal Adgangsstyring eller NemLog-In.

Adgang til API via Fælleskommunal Adgangsstyring

Brug følgende tilgang for at få adgang til API'et:

Trin 0. Forarbejde

Registrer et IT-system som anvendersystem med et OCES certifikat med offentlig nøgle i Fælleskommunal Administration:

PreProd: https://admin-test.serviceplatformen.dk/
Produktion: https://admin.serviceplatformen.dk/

Vælg "Serviceaftaler" og klik "Anmod om serviceaftale", derefter:

  1. Vælg: "Uden videregivelse af data", skriv et navn og en begrundelse
  2. Vælg det IT-system (Anvendersystem), der skal forbindes
  3. Vælg ansvarlig myndighed. Her skal vælges den myndighed som man ønsker at agere på vegne af, bemærk venligst at myndigheden skal godkende serviceaftalen før man kan få adgang til servicen.
  4. Vælg "Digitalt Samtykke API"
  5. Tilføj rolle: "Digitalt Samtykke API Adgang"
  6. Accepter vilkår og betingelser
  7. Send anmodning

Trin 1. Fremskaf adgangsbillet

Udform en POST til:

Eksterntest: https://n2adgangsstyring.eksterntest-stoettesystemerne.dk/runtime/api/rest/oauth/v1/issue
Produktion: https://n2adgangsstyring.stoettesystemerne.dk/runtime/api/rest/oauth/v1/issue

Request (POST) skal indeholde:

  1. Certifikatet som ovenfor uden privat nøgle - koblet på http-kaldet som Client Certificate
  2. En form bestående af:
    • client_id = {anvender-system-id[1]}
    • grant_type = client_credentials
    • scope = entityid:{entityId[2]},anvenderkontekst:{cvrnummer}

Dette vil returnere en token.

[1] Anvendersystemer kan findes under menupunktet It-systemer. Id'et er det UUID, som er angivet på anvendersystemets stamdata side. Det skal være id'et for det anvendersystem brugt i Trin 0.

[2] Entity_id kan findes på serviceaftalen oprettet i Trin 0. Gå til menupunktet Serviceaftaler, find den oprettede serviceaftale. I den grå kasse ved punktet Services, klik på "I"-ikonet ved "Yderligere information". I dialogboksen ses værdien for "EntityId".

Trin 2. Konverter til token, der kan anvendes af Digitalt Samtykke API

Kald af det eksterne API's Authorize endpoint (/v{N}/api/authorize/jwt) med brug af samme certifikat som Client Certificate sammen med den genererede access token som Bearer token. Her returneres en ny access token til brug mod API'et.

Trin 3. Kald Digitalt Samtykke API

Kald af API'ets endpoints (f.eks. /v{N}/api/myndighed/xxx/samtykker) med brug af samme certifikat som Client Certificate sammen med den genererede access token som Bearer token. XXX står her for cvr-nummer for myndigheden.

Adgang til API via NemLog-In

Brug følgende tilgang for at få adgang til API'et:

Trin 0. Forarbejde

  1. Opret en systembruger (Web Service Client - WSC) i NemLog-in Administration med et unikt OCES3 signeringscertifikat.

    Bemærk

    Du skal have rollen 'Web service administrator' for at kunne oprette en systembruger.

    • Preproduktion: Anvend et unikt testcertifikat under fanebladet Integration.
    • Produktion: Anvend et unikt produktionscertifikat under fanebladet Produktion.
  2. Preproduktion: Send systembrugerens EntityId og ønskede CVR-numre til digitaltsamtykke@digst.dk
  3. Produktion: Anmod om web service adgang via NemLog-in Administration:

Trin 1. Fremskaf adgangsbillet fra NemLog-in STS

Udform en POST til:

Preproduktion: https://SecureTokenService.test-nemlog-in.dk/SecurityTokenService.svc
Produktion: https://SecureTokenService.nemlog-in.dk/SecurityTokenService.svc

Request skal indeholde:

  1. Dit OCES3 signeringscertifikat (uden privat nøgle) som Client Certificate
  2. Et WS-trust kald med entityID="https://saml.wsp.digitaltsamtykke.digst.dk"
  3. Se OIO Identity Based Web Services 1.2 for referenceimplementationer

Dette vil returnere en token.

Trin 2. Konverter til token, der kan anvendes af Digitalt Samtykke API

Kald authorize endpoint med den modtagne SAML token:

Preproduktion: https://api-pp-digitaltsamtykke.ssl.digst.dk/v{N}/api/authorize/saml
Produktion: https://api-digitaltsamtykke.ssl.digst.dk/v{N}/api/authorize/saml

Anvend samme client certificate som i Trin 1 sammen med SAML token som Bearer token. Dette returnerer en JWT token til brug mod API'et.

Trin 3. Kald Digitalt Samtykke API

Kald af API'ets endpoints (f.eks. /v{N}/api/myndighed/[cvrnummer]/samtykker)

Anvend samme client certificate som Client Certificate sammen med JWT token som Bearer token.

Vigtig bemærkning

Alle requests skal indeholde det client certificate, som matcher dit signeringscertifikat.

Referenceimplementeringer

Skemaer til XML validering

XML-skemaer (XSD) bruges til validering af modtaget og afsendt XML. Se alle tilgængelige skemaer og versioner på:

Se alle XML-skemaer →

Yderligere information og support

Læs mere om Digitalt Samtykke på Digitaliseringsstyrelsens hjemmeside: https://digst.dk/it-loesninger/digitalt-samtykke/

Kontakt os på digitaltsamtykke@digst.dk

Versionshistorik

API'et er organiseret i hovedversioner (f.eks. /v1, /v2) og mindre versioner (f.eks. 1.1, 1.2, 2.1).

  • Hovedversioner markerer større ændringer i API'et, hvor der kan være væsentlige forskelle i struktur, funktionalitet og understøttelse.
  • Mindre versioner kan indeholde både nye funktioner og breaking changes, selvom de stadig ligger under samme hovedmappe.

Vigtigt

Det betyder, at integrationer udviklet til en given version (f.eks. 1.0) ikke nødvendigvis er kompatible med senere versioner (f.eks. 1.1, 1.2 eller 2.0) uden tilpasning.

For at sikre stabil drift anbefales det altid at:

  • Gennemgå versionshistorikken ved opgradering.
  • Teste integrationer op imod den version, de skal køre på i produktion.