---
task: Create, check and remove authorization groups and users with quick load
version: R1.05 (first written for R1.03)
source: IM 36K10C10-01EN 5th ed. (Feb. 2026) §2.4, §2.5; IM 36K10L45-01EN 5th ed. §4.2.2 (API key); data dictionary (`dssqld -f`); practiced on the test system 2026-09-30
status: verified on R1.03 (2026-09-30, 2026-10-06); on R1.05 the USER_DF, USER_VAL, AUTH_ACTION_DF definitions were checked identical and AUTH_GROUP_DF extended to 250 actions, AUTH_ACTION_DF and SCHEME_DF exported read-only (R1.05 test server, 2026-10-09); loading users and groups not re-tested on R1.05 (shared server, no user or group changes)
---

# Authorization groups and users (quick load)

Engineering Module equivalent: *Authorization → Authorization groups / User → Add*.
Datasets: `AUTH_GROUP_DF` (groups), `AUTH_ACTION_DF` (allowed action names), `USER_DF`
(users). Works from a normal prompt while CI Server is running. Use short relative file
names (`cd` to the folder first): long absolute paths are cut (ISS-020).

## List what exists

```
dssqld -e groups.qli -d AUTH_GROUP_DF -c -l groups.lst
dssqld -e users.qli -d USER_DF -c -l users.lst
dssqld -e actions.qli -d AUTH_ACTION_DF -c -l actions.lst
```

Installed on R1.03: groups `SYSTEM_MANAGER`, `ENGINEER`, `OPERATOR`, `GUEST`; users `ADMIN`,
`ADMINE`, `OPER`, `CI_NO_LOGIN_OPCUAS`. Passwords export as `****`. R1.05: the same four
factory groups (verified 2026-10-09); `AUTH_ACTION_DF` has 203 actions (R1.03: 200).

## Group

Required: `NAME`. Actions go in `ACTION_NAME_1`, `ACTION_NAME_2`, … (up to `ACTION_NAME_250` on
R1.04 and later, 200 on R1.03) and must be names from `AUTH_ACTION_DF` (e.g. `ITEM_READ`,
`ITEM_MODIFY_VALUE`, `SECTION_BLOCK_UNBLOCK`, `ALARM_CURRENT_ACK`). New on R1.05:
`UA_MAPPER_PROJECT_INSERT`, `_MODIFY`, `_DELETE` (dataset `UASERVER_MAPPER_DF`, OPC UA
Information Model Mapper; no `_READ` action exists). The RESTful API, pyTOOLS and API keys
have no actions of their own: a REST or Python session has the rights of the user it logs on
as (ISS-146). A group with more than 200 actions cannot be moved back to R1.03, which has only
200 action fields. Example (`examples/CI-Eng-Sample/08_auth_group_df.qli`):

```
@FIELDS
NAME,DESCRIPTION,ACTION_NAME_1,ACTION_NAME_2,ACTION_NAME_3,ACTION_NAME_4

@AUTH_GROUP_DF
"CIENG_VIEWER","CI-Eng-Sample read-only viewer","ITEM_READ","SECTION_READ","ALARM_CURRENT_READ","ALARM_CHRONO_READ"
```

## User

Required: `NAME` (≤ 32) and `AUTH_GROUP` (an existing group). Optional: `DESCRIPTION`,
`PROCESS_AREAS` (e.g. `"1-999"`), `LOGOFF_TIMEOUT` (minutes, 0–999), `INITIAL_DISPLAY`,
`LOCALE`, `ENTERPRISE`, `LAYOUT`, playback fields. Password: without a `PASSWORD` field the user
is created **without any password set** and every logon fails with *DSS-E-UNK_USER Unknown user
name/password combination*; set the password in the Engineering Module (the user does this, not
Claude). A user with an **empty** password is created by giving `PASSWORD ""` explicitly
(tested 2026-10-06, sample user `CIENG`: logon on desktop and web). Template:

```
@FIELDS
NAME,DESCRIPTION,AUTH_GROUP,PROCESS_AREAS,LOGOFF_TIMEOUT

@USER_DF
"<USER>","<description>","CIENG_VIEWER","1-999",15
```

Defaults filled in on import (seen): display authorization level 999, language *System*,
playback *HMI Client dependent* / *No*, merge priority 1. Changes take effect at the user's
next login.

## API key (RESTful API, R1.04 and later)

The RESTful API needs, besides the user's name and password (HTTP Basic), an API key of that
user in the `x-api-key` header (IM 36K10L45 §4.2; skill `data-access`). The key is made in the
Engineering Module: *Authorisation › Users*, right-click the user, *Add API Key*: key name
(user name plus a hint that it is a RESTful key), description (≤ 79 bytes), *API Type*
*RESTful API*, *Request API key*. One key per user; the manual says requesting it again gives
the **same** key, so deleting and re-requesting does not replace a leaked key — change or
remove the user instead (ISS-151, not tested).

Dataset `API_KEYS_DF` (verified definition, R1.05 2026-10-09): `NAME` = `<USER>:<KEY NAME>`
(≤ 64, upper case), `USER_NAME` (must exist in `USER_DF`), `API_KEY_NAME`, `DESCRIPTION`,
`API_TYPE` (only `RESTful API`). The key itself is **not** a field of the dataset, so it
cannot be exported or loaded with quick load; full exports skip `API_KEYS_DF` (ISS-118).
Create keys again on a new or restored system. Claude never reads, writes or stores API keys.

## Check and remove

Filtered export (`@SELECT`, see `system-management` task `export-dataset.md`):

```
@SELECT
'NAME = "<USER>"'
@USER_DF
```

Remove users first, then the group, in one `NAME`-only file (`dssqld -r`):

```
@FIELDS
NAME

@USER_DF
"<USER>"

@AUTH_GROUP_DF
"CIENG_VIEWER"
```

## Test system (R1.03, 2026-09-30)

Group `CIENG_VIEWER` and user `CIENG_TEST` (no `PASSWORD` field, logoff 15 min) loaded with 0
errors, exported back as defined, then removed (1 + 1 removed, 0 errors). Logon was not tried;
such a user cannot log on (see *User*). The group is part of CI-Eng-Sample.

## Sample user (R1.03, 2026-10-06)

`examples/CI-Eng-Sample/08b_user_df.qli`: user `CIENG`, `PASSWORD ""`, factory group `OPERATOR`,
`LAYOUT` `CIENG_Operator`, `INITIAL_DISPLAY` `CIENG_Overview`; logs on to that layout on the desktop
and on the web (no `?l=` needed). Removal (`85_remove_auth_group_df.qli`) removes the user before
the group.

**Log out all sessions of a user before removing its group**: while a session is open the group
is still referenced in `USER_VAL` and `dssqld -r` fails with *DSSP-E-NODEL … in dataset
USER_VAL*; logging out did not free it at once, and a retry in that state stopped the process
`DSSSDA03` (*DUR-F-BAD_SIZE, Negative size not allowed*; later requests failed with
*DUR-F-UNKNOWN_ATT*) until CI Server was restarted (2026-10-06, ISS-073). After a restart the
group was removed without error. `USER_VAL` exports only its header (no way to list sessions).
On R1.05 this was not repeated (it stops a DSS process; the server is shared). `USER_VAL`
and `AUTH_GROUP_DF` keep the same relation, but the DSS processes are arranged differently
(ISS-117), so treat ISS-073 as still valid until it is re-tested on a separate system (ISS-152).
The same applies to the password behaviour of ISS-072 (`USER_DF.PASSWORD` unchanged): keep
giving `PASSWORD ""` or setting the password in the Engineering Module.