User

Retrieve a list of users

GET /api/users

Retrieves a list of all registered users in OctoPrint.

Will return a 200 OK with a user list response as body.

Requires admin rights.

Status Codes:

Retrieve a user

GET /api/users/(string: username)

Retrieves information about a user.

Will return a 200 OK with a user record as body.

Requires either admin rights or to be logged in as the user.

Parameters:
  • username – Name of the user which to retrieve
Status Codes:

Add a user

POST /api/users

Adds a user to OctoPrint.

Expects a user registration request as request body.

Returns a list of registered users on success, see Retrieve a list of users.

Requires admin rights.

JSON Parameters:
 
  • name – The user’s name
  • password – The user’s password
  • active – Whether to activate the account (true) or not (false)
  • admin – Whether to give the account admin rights (true) or not (false)
Status Codes:
  • 200 OK – No error
  • 400 Bad Request – If any of the mandatory fields is missing or the request is otherwise invalid
  • 409 Conflict – A user with the provided name does already exist

Update a user

PUT /api/users/(string: username)

Updates a user record.

Expects a user update request as request body.

Returns a list of registered users on success, see Retrieve a list of users.

Requires admin rights.

Parameters:
  • username – Name of the user to update
JSON Parameters:
 
  • admin – Whether to mark the user as admin (true) or not (false), can be left out (no change)
  • active – Whether to mark the account as activated (true) or deactivated (false), can be left out (no change)
Status Codes:

Delete a user

DELETE /api/users/(string: username)

Delete a user record.

Returns a list of registered users on success, see Retrieve a list of users.

Requires admin rights.

Parameters:
  • username – Name of the user to delete
Status Codes:

Reset a user’s password

PUT /api/users/(string: username)/password

Changes the password of a user.

Expects a JSON object with a single property password as request body.

Requires admin rights or to be logged in as the user.

Parameters:
  • username – Name of the user to change the password for
JSON Parameters:
 
  • password – The new password to set
Status Codes:

Retrieve a user’s settings

GET /api/users/(string: username)/settings

Retrieves a user’s settings.

Will return a 200 OK with a JSON object representing the user’s personal settings (if any) as body.

Requires admin rights or to be logged in as the user.

Parameters:
  • username – Name of the user to retrieve the settings for
Status Codes:

Update a user’s settings

PATCH /api/users/(string: username)/settings

Updates a user’s settings.

Expects a new settings JSON object to merge with the current settings as request body.

Requires admin rights or to be logged in as the user.

Parameters:
  • username – Name of the user to retrieve the settings for
Status Codes:

Regenerate a user’s personal API key

POST /api/users/(string: username)/apikey

Generates a new API key for the user.

Does not expect a body. Will return the generated API key as apikey property in the JSON object contained in the response body.

Requires admin rights or to be logged in as the user.

Parameters:
  • username – Name of the user to retrieve the settings for
Status Codes:

Delete a user’s personal API key

DELETE /api/users/(string: username)/apikey

Deletes a user’s personal API key.

Requires admin rights or to be logged in as the user.

Parameters:
  • username – Name of the user to retrieve the settings for
Status Codes:

Data model

User list response

Name Multiplicity Type Description
users 0..n List of user records The list of registered users

User record

Name Multiplicity Type Description
name 1 string The user’s name
active 1 bool Whether the user’s account is active (true) or not (false)
user 1 bool Whether the user has user rights. Should always be true.
admin 1 bool Whether the user has admin rights (true) or not (false)
apikey 0..1 string The user’s personal API key
settings 1 object The user’s personal settings, might be an empty object.

User registration request

Name Multiplicity Type Description
name 1 string The user’s name
password 1 string The user’s password
active 1 bool Whether to activate the account (true) or not (false)
admin 0..1 bool Whether to give the user admin rights (true) or not (false or not present)

User update request

Name Multiplicity Type Description
active 0..1 bool If present will set the user’s active flag to the provided value. True for activating the account, false for deactivating it.
admin 0..1 bool If present will set the user’s admin flag to the provided value. True for admin rights, false for no admin rights.