Managing Users

Create, read, update and delete users via the REST API.

User list (admin)

Users are stored as a synchronized list resource at labcontrol.users. You need LAB_ADMIN, IS_ADMIN, or LAB_SEE_USERS permissions to access this resource.

List all users

curl http://your-server/api/lists/labcontrol.users \
  -H "Authorization: Bearer $TOKEN"

The response is a JSON array. Each item contains a data object with the user fields and a uuid at the top level:

[
  {
    "data": {
      "name": "Max",
      "surname": "Mustermann",
      "mail": "max@fablab.org",
      "alias": "maxm",
      "role": "mem",
      "course": "",
      "balance": 1500,
      "creditLimit": -1,
      "state": 1,
      "lastLogin": "2024-01-15T10:30:00.000",
      "creation": "2023-06-01T08:00:00.000",
      "uuid": "f47ac10b58cc4372a5670e02b2c3d479"
    },
    "uuid": "f47ac10b58cc4372a5670e02b2c3d479"
  }
]

Field reference:

Field	Type	Description
`name`	string	First name
`surname`	string	Last name
`mail`	string	Email address
`alias`	string	Display name (chosen by user)
`role`	string	`mem` (member), `empl` (employee), `ext` (external/guest)
`course`	string	Course or semester (e.g. `WS2024`)
`balance`	int	Account balance in cents
`creditLimit`	int	Maximum negative balance in cents. `-1` = use global default
`state`	int	`0` = idle, `1` = active, `2` = disabled, `3` = deleted
`lastLogin`	string	ISO 8601 timestamp of last login
`creation`	string	ISO 8601 timestamp of account creation
`uuid`	string	Unique user ID

Get a single user

By UUID:

curl http://your-server/api/lists/labcontrol.users/f47ac10b58cc4372a5670e02b2c3d479 \
  -H "Authorization: Bearer $TOKEN"

By index (0-based position in the list):

curl http://your-server/api/lists/labcontrol.users/0 \
  -H "Authorization: Bearer $TOKEN"

Update user properties

To change individual properties of an existing user, use PATCH. Only the fields you specify are changed:

curl -X PATCH http://your-server/api/lists/labcontrol.users/f47ac10b58cc4372a5670e02b2c3d479 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "role": "empl"
    }
  }'

Replace a user record

If you want to replace the entire user object, use PUT:

curl -X PUT http://your-server/api/lists/labcontrol.users/f47ac10b58cc4372a5670e02b2c3d479 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "Max",
      "surname": "Mustermann",
      "mail": "max@fablab.org",
      "role": "empl",
      "balance": 3000
    }
  }'

Note:

PUT replaces the entire item. Any fields you omit will be lost. Use PATCH if you only want to update specific properties.

Remove a user

curl -X DELETE http://your-server/api/lists/labcontrol.users/f47ac10b58cc4372a5670e02b2c3d479 \
  -H "Authorization: Bearer $TOKEN"

Add a user via the lab service

To create a new user with permissions, cards, and group assignments in one step, use the lab service. This is the recommended way to add users because it handles all related data at once. You need LAB_ADMIN or LAB_MODIFY_USERS permissions.

curl -X POST http://your-server/api/services/lab/addUser \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "name": "Lisa",
      "surname": "Lasercut",
      "mail": "lisa@fablab.org",
      "role": "mem"
    },
    "permissions": {},
    "card": {},
    "groups": {}
  }'

To create a user or update them if they already exist (useful for CSV imports), use addOrUpdateUser:

curl -X POST http://your-server/api/services/lab/addOrUpdateUser \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "name": "Lisa",
      "surname": "Lasercut",
      "mail": "lisa@fablab.org",
      "role": "mem"
    },
    "permissions": {},
    "card": {},
    "groups": {}
  }'

Delete a user via the lab service

curl -X POST http://your-server/api/services/lab/deleteUser \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userID": "f47ac10b58cc4372a5670e02b2c3d479"}'

Transfer money

To add or deduct credit from a user’s balance, use the transferMoney method. The value is in cents (positive = credit, negative = debit). Requires LAB_ADMIN or LAB_SERVICE permissions.

curl -X POST http://your-server/api/services/lab/transferMoney \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userID": "f47ac10b58cc4372a5670e02b2c3d479",
    "value": 500,
    "description": "Workshop fee refund"
  }'

Parameter	Type	Required	Description
`userID`	string	yes	UUID of the user
`value`	int	yes	Amount in cents
`description`	string	no	Reason for the transfer

Reset a user’s password

Sends a temporary password to the user by email:

curl -X POST http://your-server/api/services/lab/resetPassword \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userID": "f47ac10b58cc4372a5670e02b2c3d479"}'

Look up a user by card ID

Requires LAB_ADMIN, LAB_SERVICE, or LAB_SEE_USERS permissions.

curl -X POST http://your-server/api/services/lab/getUserForCard \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cardID": "04:A3:2B:1C:D4:E5:F6"}'

Look up a user by external reference

If users are linked to an external system via extRef, you can look them up:

curl -X POST http://your-server/api/services/lab/getUserForExternalReference \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"extRef": "EXT-12345"}'

Response:

{
  "errorCode": 0,
  "userID": "f47ac10b58cc4372a5670e02b2c3d479",
  "userName": "Max",
  "eMail": "max@fablab.org",
  "balance": 1500
}

If no user is found, errorCode is -1.

Reading your own user data

To read the data of the currently logged-in user as an object resource, use labcontrol.user (singular). This does not require admin permissions.

curl http://your-server/api/objects/labcontrol.user \
  -H "Authorization: Bearer $TOKEN"

The response wraps each property in a data field:

{
  "name": {"data": "Max"},
  "surname": {"data": "Mustermann"},
  "mail": {"data": "max@fablab.org"},
  "alias": {"data": "maxm"},
  "role": {"data": "mem"},
  "balance": {"data": 1500},
  "state": {"data": 1},
  "creditLimit": {"data": -1},
  "course": {"data": ""},
  "lastLogin": {"data": "2024-01-15T10:30:00.000"},
  "creation": {"data": "2023-06-01T08:00:00.000"},
  "uuid": {"data": "f47ac10b58cc4372a5670e02b2c3d479"}
}

Read a single property

curl http://your-server/api/objects/labcontrol.user/balance \
  -H "Authorization: Bearer $TOKEN"

Update your own profile

Regular users can only modify their alias:

curl -X PUT http://your-server/api/objects/labcontrol.user/alias \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": "my-new-alias"}'

Admins (LAB_ADMIN, IS_ADMIN, or LAB_MODIFY_USERS) can additionally modify name, surname, mail, role, course, creditLimit, and extRef.