Kom i gang med utstedertjenesten

Innhold

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

Oversikt

Utstedertjenesten lar dere sende digitale bevis (Verifiable Credentials) til en lommebok-eier. Beviset kan leveres på to måter:

Oversikt over utstedelsesflyt

  • Digipost: Lommebok-eieren får en Digipost-melding med en QR-kode/deep link og henter beviset i lommeboken.
  • Direct: Dere mottar en credential offer-URI som dere selv presenterer, for eksempel som QR-kode eller deep link i deres egen nettside eller app.

Flyten er oppsummert slik:

  1. Dere oppretter en utstedelse via API-et (POST).
  2. Beviset klargjøres og leveres, enten via Digipost-postkassen eller som en URI dere håndterer selv.
  3. Beviset hentes i lommeboken.
  4. Dere poller etter status via API-et (GET) til beviset er hentet.

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 utstede bevis må en bevismal (credential template) opprettes hos Digipost. Malen definerer hvilken type bevis som kan utstedes og hvilke felter (claims) beviset inneholder.

Ta kontakt med Digipost for å få dette på plass. Dere vil få utlevert:

  • En credentialTemplateId som identifiserer bevismalen
  • Brukernavn og passord for API-tilgang

Utstedersertifikat

Alle utstedere har et utstedersertifikat som brukes til å signere bevisene som utstedes. Sertifikatet vises i lommeboken og bekrefter hvem som har utstedt beviset. Les mer om tillit og sertifikater.

For testformål brukes Digipost sitt felles utstedersertifikat. Dersom dere ønsker å vises med eget navn i lommeboken, kan dere registrere eget utstedersertifikat.

Se også testressurser for lommebok, testpostkasse og nasjonal sandkasse.

Testmiljø

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

Leveringsmetoder

Digipost

Lommebok-eieren får en melding i Digipost-postkassen med en QR-kode eller deep link. Når meldingen åpnes og QR-koden skannes (eller lenken trykkes), hentes beviset automatisk i lommeboken. Meldingen leveres til privat postkasse (person) eller virksomhetspostkasse (organisasjon).

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

Direct

Dere mottar en credentialOfferUri som dere presenterer, for eksempel som QR-kode eller deep link. URI-en åpnes i lommeboken for å hente beviset.

Typiske integrasjonsflyter

Digipost-flyt 

1. POST /api/v2/issuance  (method: digipost, recipientId: ...)  →  201
2. (Lommebok-eieren får Digipost-varsel, åpner det og henter bevis via lommebok)
3. GET  /api/v2/issuance/{issuanceId}  →  200, status: PENDING → ACTIVE → ISSUED

Direct-flyt 

1. POST /api/v2/issuance  (method: direct)  →  201
2. POST /api/v2/issuance/{issuanceId}/credential-offer  →  201, credentialOfferUri
3. (Presenter credentialOfferUri, f.eks. QR-kode eller deep link)
4. (URI-en åpnes i lommeboken og beviset hentes)
5. GET  /api/v2/issuance/{issuanceId}  →  200, status: ISSUED

Mulige statuser

Status Betydning
PENDING Utstedelsen er opprettet. Beviset er ennå ikke hentet.
ACTIVE Credential offer er opprettet og tilgjengelig. Venter på at beviset hentes i lommeboken.
ISSUED Beviset er hentet og lagret i lommeboken.
FAILED Noe gikk galt under utstedelsen.