# 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 [Skjalaveita API](/products/postholf/postholf-03-interface-skjalaveita.md#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 [Skjalaveita API](/products/postholf/postholf-03-interface-skjalaveita.md#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 [Skjalaveita API](/products/postholf/postholf-03-interface-skjalaveita.md#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](#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="/files/9Q66ps7mCC2iSc5D9EWk" 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.

![](/files/SyRWAXnrUVTbEE1lqIcV)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.devland.is/products/postholf/postholf-03-interface-skjalaveita.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.