Kom i gang med verifiseringstjenesten

Innhold

  1. Oversikt
  2. Forberedelse
    1. Brukerstedssertifikat
  3. Testmiljø
  4. Leveringsmetoder
    1. Digipost
    2. Direct
  5. Typiske integrasjonsflyter
    1. Digipost-flyt
    2. Direct-flyt
    3. Mulige statuser

Oversikt

Verifiseringstjenesten lar dere forespørre bevis (Verifiable Credentials) fra en mottaker. Bestillingen kan formidles på to måter:

Oversikt over verifiseringsflyt

  • Digipost: Mottakeren får en melding i Digipost-postkassen med en QR-kode/deep link og deler beviset via sin lommebok.
  • Direct: Dere mottar en authorization request-URI som dere selv presenterer for mottakeren, for eksempel som QR-kode eller deep link i deres egen nettside eller app.

Flyten er oppsummert slik:

  1. Dere oppretter en verifisering via API-et (POST).
  2. Forespørselen leveres, enten via Digipost-postkassen eller som en URI dere håndterer selv.
  3. Mottakeren deler beviset via sin lommebok.
  4. Beviset verifiseres og resultatet lagres.
  5. Dere poller etter resultatet via API-et (GET) til det er klart.

Swagger UI er den primære API-dokumentasjonen. Der finner dere request/response-skjemaer, eksempler, feilkoder, autentiseringsdetaljer og øvrige felt som ikke er beskrevet her. API-spesifikasjonen er også tilgjengelig som OpenAPI 3 (JSON).

Forberedelse

Før dere kan verifisere bevis trenger dere:

  • Brukernavn og passord for API-tilgang
  • VCT-verdier (Verifiable Credential Type) som identifiserer hvilke bevistyper dere ønsker å forespørre. Disse brukes i credentialQuery.credentials[].meta.vct_values

Ta kontakt med Digipost for å få dette på plass. Se også testressurser for lommebok, testpostkasse og nasjonal sandkasse.

For å teste verifisering må lommeboken inneholde bevis som matcher forespørselen. Ta kontakt med Digipost for å få tilgang til testbevis.

Brukerstedssertifikat

Alle verifiserere har et brukerstedssertifikat som brukes til å signere authorization requests. Sertifikatet vises i mottakerens lommebok og bekrefter hvem som ber om beviset. Les mer om tillit og sertifikater.

For testformål tilbyr Digipost et felles brukerstedssertifikat som standard. Dersom dere ønsker å vises med eget navn i lommeboken, kan dere registrere eget brukersted og sertifikat:

  1. Registrer brukerstedet i Digdirs selvbetjeningsløsning (krever Altinn-rettigheter for virksomheten).
  2. Digipost genererer en sertifikatforespørsel (CSR) som dere laster opp og får signert av Digdir.
  3. Det signerte sertifikatet registreres hos Digipost og tas i bruk.

Ta kontakt med Digipost for å komme i gang med eget brukerstedssertifikat.

Testmiljø

  • Base-URL: https://lommebok.test.digipost.no/verifiserer
  • Autentisering: Basic Auth (OAuth 2.0 kommer)
  • Brukernavn/passord: Oversendes

Leveringsmetoder

Digipost

Mottakeren får en melding i Digipost-postkassen med en QR-kode eller deep link. Når mottakeren åpner meldingen og skanner QR-koden (eller trykker på lenken), starter verifiseringsflyten i lommeboken.

Bruk "method": "digipost" og oppgi recipientId (fødselsnummer eller organisasjonsnummer), presentationNoticeTitle og presentationNoticeBody.

Direct

Dere mottar en authorizationRequestUri som dere selv presenterer for mottakeren, for eksempel som QR-kode eller deep link. Mottakeren åpner URI-en i sin lommebok og deler beviset.

Flyten ved Direct-levering:

  1. Opprett en verifisering (POST /api/v2/verification) med "method": "direct".
  2. Hent authorization request-URI (POST /api/v2/verification/{verificationId}/authorization-request).
  3. Presenter authorizationRequestUri til mottakeren (QR-kode, deep link e.l.).
  4. Mottakeren deler beviset via sin lommebok.
  5. Poll etter resultat (GET /api/v2/verification/{verificationId}).

Typiske integrasjonsflyter

Digipost-flyt 

1. POST /api/v2/verification  (method: digipost, recipientId: ...)  →  201
2. (Mottakeren får bestillingsbrev, åpner brevet, deler bevis via lommebok)
3. GET  /api/v2/verification/{verificationId}  →  200, status: PENDING → ACTIVE → PRESENTED

Direct-flyt 

1. POST /api/v2/verification  (method: direct)  →  201
2. POST /api/v2/verification/{verificationId}/authorization-request  →  201, authorizationRequestUri
3. (Presenter authorizationRequestUri til mottakeren, f.eks. QR-kode eller deep link)
4. (Mottakeren åpner URI-en i sin lommebok og deler beviset)
5. GET  /api/v2/verification/{verificationId}  →  200, status: PRESENTED

Mulige statuser

Status Betydning
PENDING Verifiseringen er opprettet. Mottakeren har ikke åpnet bestillingsbrevet ennå.
ACTIVE Mottakeren har åpnet brevet og en authorization request er sendt til lommeboken.
PRESENTED Beviset er mottatt og verifisert. presentation inneholder bevisdata.
FAILED Noe gikk galt under verifiseringen.