Documentation

CoAP PUT /iam/users/:username/:setting

DESCRIPTION

This endpoint is used to set/change the settings of a particular user of the device.

DECLARATION

PUT /iam/users/:username/:setting

The following settings exists on a user:

  • username - string: Change the username uniquely identifying the user on this device. The username is restricted to the characters a-z, 0-9, _, -, and ..
  • display-name - string: Set a UTF-8 string describing a user with more freedom than the username.
  • password - string: Set a password to use for password invite pairing.
  • role - string: Set a role for the user.
  • sct - string: Set a server connect token for the user.
  • oauth-subject - string: Set an OAuth subject for the user.
  • fcm - map: Set FCM information for the user to enable the device to send mobile push notificatons. It is a map with two keys ProjectId and Token, see below.
  • notification-categories - array: Set FCM notification categories for the user. It is an array of strings, see below.

Deprecated user settings:

  • fingerprint - string: Set client fingerprint. Use add and remove fingerprints.

REQUESTS

The request body contains the value to set for the particular setting encoded as CBOR, for example a valid username as string:

john_doe

For display-name, password, oauth-subject, and fingerprint sending the null-value as body will clear that setting on the user.

For the fcm setting, a CBOR encoded string map must be provided:

{
   "ProjectId": "fir-nabto-demo",
   "Token": "eARPXJ9c60xUk05BM5svHO:APA91cEjzeq7R9iAWx9sYGjj26RoaJ13bfO8eeu741J7GigVWWxYijOJMjcuG52lFjr3sziXpBvpOZh41dfSOZ5mRj4jwFdJk06DWZ3pMxfPPyWVqHCjxPrWWZ2FOOY6tEvwIRFh0_ar"
}

For the notification-categories setting, a CBOR encoded array of notification category names must be provided:

["WARNING", "CRITICAL"]

RESPONSE

CoAP status codes:

  • 204: If the setting was set.
  • 400: The request body was invalid. For the notification-categories setting, this means one or more categories requested are invalid. Valid categories configured on the device can be listed with CoAP GET /iam/notification-categories
  • 403: Blocked by IAM configuration.
  • 404: The username does not exist, the setting does not exist or the referenced role does not exist.
  • 409: Provided username/fingerprint not unique.

IAM PARAMETERS

Each setting has its own IAM Action which the user must have access to to use this endpoint:

  • IAM:SetUserUsername
  • IAM:SetUserDisplayName
  • IAM:SetUserFingerprint
  • IAM:SetUserPassword
  • IAM:SetUserSct
  • IAM:SetUserOauthSubject
  • IAM:SetUserRole
  • IAM:SetUserFcm
  • IAM:SetUserNotificationCategories

This endpoint always provides the additional attribute:

  • IAM:Username

Additionally, when setting, the role setting the following attribute is provided:

  • IAM:RoleId