# Security and access

> How Konstrukt controls who can see and change what — users, roles and groups, access lists, app and dataset access, sensitive value types, single sign-on and machine credentials.

Access in Konstrukt is layered. Authentication decides who a user is (single sign-on or a Konstrukt login). Authorization then works from the outside in: which **plans** a user can open, which **apps** inside a plan, which **rows** of each dataset they can read or write, and — for sensitive measures — whether they can see the **value** at all. Machine access (APIs, SQL, file transports, MCP) uses separate credentials that are described at the end of this page.

## Access model at a glance

| Layer | Controls | Configured in |
|---|---|---|
| Users, roles, groups | Who exists and which roles they hold | Users (*Användare*) |
| Plan access | Which plans a user sees at all | User administration |
| Access lists (*Behörighetslistor*) | Rules that grant read or read/write per role or group, optionally limited by dimension values | Plan admin → Interaction (*Interaktion*) |
| App access (*Appåtkomst*) | Whether an app is enabled, locked, and which access list governs it | App settings (*Inställningar*) |
| Dataset access | Read or read/write per dataset, inherited from the app or from a chosen list | App settings, per dataset |
| Sensitive value types | Hides the value of a measure while the row stays visible | Value type settings |
| Locked values, calculated data | Not access control, but they also make cells read-only | Dataset configuration, calculations |

A user's effective permission on a cell is the most restrictive result of these layers.

## Users, roles and groups

The Users area (*Användare*) in the left rail has three views: Users, Roles and Groups (*Användare · Roller · Grupper*).

- **Users** carry roles, plan access and a user type.
- **Roles** are the unit that access lists grant permissions to. A role can be linked to groups.
- **Groups** bundle roles. Access list rules can target either a role or a group.

Users only see plans they have access to; everything below the plan level (apps, datasets, rows) is filtered further by access lists.

Through MCP, `get_users` returns each user's login ID, UPN (e-mail), display name, user type (for example `Konstrukt.SysAdmin`) and role names. `get_roles` returns each role with its linked groups. Neither shows individual permissions.

### Act as

Administrators can switch to another role with **Act as** (*Agera som*) in the top bar and see apps exactly as that role would. Use it to verify an access list or a dataset restriction before publishing an app to end users.

## Access lists

Access lists (*Behörighetslistor*) belong to a plan and are found in the plan admin under Interaction (*Interaktion*), described in the product as "control which data each group can see".

An access list has:

| Field | Meaning |
|---|---|
| Description (*Beskrivning*) | Free text |
| Limit permission based on dimension (*Begränsa behörighet baserat på dimension*) | When on, rules restrict access to specific dimension values (for example a user sees only their own `Department` values) |
| Rules | A grid of role or group × permission type, for example Read & write (*Läsa & Skriva*) |

The same list can be reused by several apps, datasets and action-component inputs. In app configuration a list is referenced by `AccessListId` on `AppAccess`, on a dataset's `RowLevelAccess`, and on dimension or property variables of action components (so a form only offers values the user may use).

Through MCP, a rule without dimension restriction is returned as a role name and an access level, for example `{"roleName": "CFO", "accessLevel": "ReadWrite"}`. Rules have no priority or ordering field.

!!! agent "For agents"
    Read rules with `get_access_rules(planId, accessListId)` and write them with `import_access_rules`. Import modes are `Insert`, `Update`, `Upsert` (default) and `Replace`. `Replace` removes rules not in the payload — confirm with the user first. The `accessListId` has to be taken from an existing app config (`AppAccess.AccessListId`, `RowLevelAccess.AccessListId`) because no tool lists access lists.

## App access

Each app has an access section in its settings (**Settings** → **App access**, *Inställningar* → *Appåtkomst*):

| Setting | Effect | JSON (`Access`) |
|---|---|---|
| Enabled | Whether the app is available | `Enabled` |
| Lock app (*Lås appen*) | Locks the app for editing | `Locked` |
| Access list | Which list controls who can open the app | `AccessListId` — `null` grants full access for everyone |

## Dataset access

Every dataset in an app has its own access setting, so one app can combine a dataset everyone may edit with a read-only dataset that only some roles see.

| GUI choice | Meaning |
|---|---|
| Read (*Läsåtkomst*) | Rows can be read, not edited |
| Read and write (*Läs- och skrivåtkomst*) | Rows can be read and edited |
| Inherit from app (*Ärv från app*) | Uses the app's access list |
| Full | Full access; no access list applied to the dataset |
| Choose list (*Välj lista*) | Uses a specific access list for this dataset |

In the configuration JSON this is `RowLevelAccess`, discriminated by `$type`:

| `$type` | Fields | Meaning |
|---|---|---|
| `Inherit` | `ReadOnly`, `EnableDimensionBasedAccess` | Inherit from the app; optionally apply dimension-based rules |
| `Limit` | `ReadOnly`, `AccessListId` | Restrict to a specific access list |

```json
"RowLevelAccess": { "$type": "Limit", "ReadOnly": true, "AccessListId": 12 }
```

How the GUI choice *Full* maps to the JSON types, and exactly what a locked app prevents, are tracked as open questions on [Datasets](datasets.html#row-level-access) and [Apps](apps.html). See [Datasets](datasets.html) for the rest of the dataset configuration.

## Sensitive value types

A value type can be marked sensitive (`isSensitive`, **Sensitive data**, *Känslig data*). For affected users the rows stay visible — the dimension combination is shown — but the **value itself is hidden**. It hides the measure, not the row.

Typical use: a user who administers dimensions and imports data into a value type holding salaries, but must not see the salary amounts.

Seeing sensitive values is a specific permission that is assigned to roles. By default a tenant has three roles with some form of admin access:

| Role | Sensitive values |
|---|---|
| Admin | Visible |
| Builder | Visible |
| Limited Builder | Hidden |

Where sensitive values are hidden:

| Surface | Sensitive values |
|---|---|
| Apps and the admin interface | Hidden for users without the permission |
| Exports from the interface | Hidden for users without the permission |
| External SQL views | **Not hidden.** A tenant has a single SQL integration account, which sees all data |

Grant SQL access only to consumers that are allowed to see all data, including sensitive value types.

## Read-only cells that are not access control

Some cells are read-only for reasons unrelated to permissions. The grid shows the reason on hover:

| Tooltip reason | Cause | What the user can do |
|---|---|---|
| Locked by Locked Values | The dataset's Locked values (`LockedValues`) cover the cell | Ask an administrator |
| Calculated value | A calculation wrote the value | Change the calculation's sources |
| Expression has no writeback | An expression column without a writeback expression | Enter the value on the underlying value type |

See [Datasets](datasets.html) and [Calculations](calculations.html).

## Sign-in

A tenant can allow several sign-in methods in parallel. Each method is switched on or off per tenant.

| Method | Description |
|---|---|
| Microsoft account | Sign-in with a Microsoft work account |
| Google account | Sign-in with a Google account |
| Internal account | User name and password, managed in Konstrukt. No multi-factor authentication. |
| Custom single sign-on | The customer's own identity provider over **OpenID Connect** (OAuth 2.0) or **SAML** |

Authentication is being rebuilt as part of the move to the new hosting environment in 2026. After the move, sign-in with Microsoft and Google accounts is available to all users by default.

!!! tip "Requiring MFA"
    Internal accounts have no multi-factor authentication. To require MFA, use Microsoft, Google or custom single sign-on with an identity provider that enforces it, and switch off internal accounts for the tenant.

### Custom single sign-on with OpenID Connect

Konstrukt enables custom SSO for the tenant once the provider details have been registered. Current requirements:

| Item | Value |
|---|---|
| Redirect URI | `https://oauth.konstrukt.app/api/signin/{tenant}` — `{tenant}` is the tenant's subdomain (the `{tenant}` in `{tenant}.konstrukt.app`) |
| User identifier | A `upn` claim in the ID token; each Konstrukt user must have the matching UPN |
| Flow | Implicit grant for ID and access tokens |

Example with Microsoft Entra ID as the customer's own provider:

1. Create an **App registration**; set a **Web** redirect URI (above).
2. Under **Authentication**, allow implicit grant for access tokens and ID tokens.
3. Under **Certificates & secrets**, create a client secret and store it — it is shown once.
4. Under **Token configuration**, add the optional claim `upn` to the ID token. The UPN must already exist on the users in the directory.
5. Send Konstrukt, over a secure channel, the **Directory (tenant) ID**, **Application (client) ID** and the **client secret**.
6. Add each user's UPN to the corresponding Konstrukt user (the directory's user export helps).
7. Konstrukt enables SSO for the tenant.

### Passwords and sessions

- When a password is set for an internal account, Konstrukt generates a long random password (at least 10 characters).
- Sessions are long-lived: a sign-in lasts at least about 30 days.

!!! agent "For agents"
    `import_users` creates users but **no logins**; it is only practical on tenants that use SSO, where the login comes from the identity provider and is matched on UPN. `import_users` defaults to mode `Insert`; `import_groups` and `import_roles` default to `Upsert`. `get_users` returns active users with roles, plan access and user type.

## Machine credentials

Non-interactive access uses dedicated credentials, each scoped to one surface:

| Credential | Used for | Created in |
|---|---|---|
| API key (Key ID + API key) | REST API via OAuth 2.0 client credentials; KDI command-line importer | Integration → API keys (*API-nycklar*) |
| SAS token | Uploading import files to the Azure storage container | Integration → Accounts (*Konton*) |
| SFTP account | Uploading import files over SFTP | Integration → Accounts |
| SQL integration account | Reading external SQL views; user ID, generated password and IP allow-list | Integration → Accounts |
| MCP client | AI agents; tools are filtered by the caller's privileges | See [AI agents and MCP](ai-agents.html) |

An **API key** is issued by an administrator for a chosen user, and carries that user's permissions in the API. It does not grant anything the user cannot do. A key is valid for **one year** by default. Create a new key before the old one expires, and update the integrations that use it.

The key list shows purpose (*Ändamål*), user name, expiry date (*Giltig till*) and the **Master key** flag (*Huvudnyckel*). A master key can emulate other users, which applies only to legacy (v1) plans. In v2 plans, users switch between their roles instead (see [Act as](#act-as)), and no master key is needed. Leave *Huvudnyckel* unticked.

The SQL integration account is one account per tenant and only accepts connections from allow-listed IP addresses.

## Traceability

Every value and dimension value carries edit metadata (who and when, `$editby`, `$edittime`), and changes are kept in history. Deleting data does not delete its history. See [References and history](references-history.html) and [Traceability](traceability.html).

## Hosting, encryption and backup

The service is hosted in Sweden. Each tenant has its own database, and data is encrypted in transit and at rest. See [Hosting and operations](operations.html) for sub-processors, backup and restore, and releases.

## Related

- [Datasets](datasets.html)
- [Data integration](integration.html)
- [APIs and SQL access](apis.html)
- [AI agents and MCP](ai-agents.html)
- [Tenant administration](administration.html)
