Skjalaveita API

Skjalaveita API

Service that document providers need to implement. All document providers need to implement the same interface. The mailbox will call this service to retrieve documents from the document provider when a user wants to view the document.

HTTPS communication is required. The backend system will identify itself with JWT in the Authorization header using the Bearer schema. The service MUST validate the signature, issuer, expiry dates, audience and scope

Document

The operation returns an owner's document. The service should only return a document if the documentId and owner_kennitala matches a registered document in the document provider's system.

GET $BASE_URL$/{kennitala}/documents/{documentId}?authenticationType={authenticationType}&includeDocument={includeDocument}

Request Parameters:

Variable	Type	Description
kennitala	String	Owners/recipients kennitala.
documentId	String	A unique identifier for the reference within the document provider.
authenticationType	String	Strength of authentication of the user/recipient of the document. LOW = User/pass SUBSTANTIAL = Two factor authentication (User/Pass and additionally SMS) HIGH = Client Certificate
includeDocument	Boolean	If the actual document should be returned or only the metadata

Response:

{
  "type": "string",
  "content": "string",
  "actions": [
    {
      "type": "string",
      "title": "string",
      "data": "string",
      "icon": "string" 
    }
  ]
}

Property name	Type	Description
type	String	Document form (file ending). For example, pdf. If nothing is given, pdf is the default and recommended if there is not a special reason for something else.
content	Base64Binary (String)	The document/file content base64 encoded.
actions	List(Action)	See Actions
Or
type	String	If set to “url”, island.is will redirect the user to a document delivery site. User is transferred between along with a signed SAML2 xml.
content	String	Url
actions	List(Action)	See Actions
Or
type		If set to “html”, page with the html content will be displayed in new tab.
content	String	Html to display the user. The HTML must contain all "inline" to display. HTML must not contain javascript.
actions	List(Action)	See Actions

Actions

Actions are optional, they provide additional actions for the end user. Actions appear as buttons above the document once it has been opened.

Property name	Type	Description
type	string	The type of action
title	string	The text the button displays
data	string	See Supported actions
icon	string	The icon on the action button list of supported icons

Supported actions

type	data	Description
file	-	Opens the document in a new tab
url	string	A url

Example

[
    {
        Type = "url",
        Title = "Mínar síður",
        Data = "https://island.is/minarsidur/",
        Icon = "open"
    },
    {
        Type = "file",
        Title = "Sækja sem PDF"
    }
]

Sequence Diagram

Sequence diagram that describes how Island.is retrieves a document and displays the user. This is valid when documents that are in the form of a non-external connection are required, such as pdf.