# 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  | <p>Strength of authentication of the user/recipient of the document.<br>LOW = User/pass<br>SUBSTANTIAL = Two factor authentication (User/Pass and additionally SMS)<br>HIGH = Client Certificate</p> |
| includeDocument    | Boolean | If the actual document should be returned or only the metadata                                                                                                                                       |

Response:

```json
{
  "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](#actions "mention")                                                                                                                          |
| **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](#actions "mention")                                                                                                                          |
| **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 "mention")                                                                                                                          |

## 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](#supported-actions "mention")                                                                                                  |
| icon          | string | The icon on the action button [list of supported icons](https://github.com/island-is/island.is/blob/main/libs/island-ui/core/src/lib/IconRC/iconMap.ts) |

### Supported actions

<table><thead><tr><th width="374">type</th><th>data</th><th>Description</th><th data-hidden></th></tr></thead><tbody><tr><td>file</td><td>-</td><td>Opens the document in a new tab</td><td></td></tr><tr><td>url</td><td>string</td><td>A url</td><td></td></tr></tbody></table>

### Example

<figure><img src="https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2FMBbANFKidOgmbZIrSNZK%2Fimage.png?alt=media&#x26;token=bcfdfb0e-73a0-4db0-976a-f4a126eee55b" alt=""><figcaption></figcaption></figure>

```json
[
    {
        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.

![](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-1829beba037574a6c391accc9b8fcb18647d59d9%2Fsequence-diagram.png?alt=media)