Access control

Permissions

List all permissions

GET /api/access/permissions

Retrieves all permissions available in the system.

Will return a 200 OK with a permission list as body.

Status Codes:

Groups

Get group list

GET /api/access/groups

Retrieves all groups registered in the system.

Will return a 200 OK with a group list as body.

Requires the SETTINGS permission.

Status Codes:

Add a new group

POST /api/access/groups

Adds a new group to the system.

Expects a group registration request as request body.

Will return a group list response on success.

Requires the SETTINGS permission.

JSON Parameters:
 
  • key – The group’s identifier
  • name – The user’s name
  • description – A human readable description of the group
  • permissions – The permissions to assign to the group
  • subgroups – Subgroups assigned to the group
  • default – Whether the group should be assigned to new users by default or not
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 group with the provided key does already exist

Retrieve a group

GET /api/access/groups/(string: key)

Retrieves an individual group record.

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

Requires the SETTINGS permission.

Status Codes:

Update a group

PUT /api/access/groups/(string: key)

Updates an existing group.

Expects a group update request as request body.

Will return a group list response on success.

Requires the SETTINGS permission.

JSON Parameters:
 
  • description – A human readable description of the group
  • permissions – The permissions to assign to the group
  • subgroups – Subgroups assigned to the group
  • default – Whether the group should be assigned to new users by default or not
Status Codes:
  • 200 OK – No error
  • 400 Bad Request – If any of the mandatory fields is missing or the request is otherwise invalid

Delete a group

DELETE /api/access/groups/(string: key)

Deletes a group.

Will return a group list response on success.

Requires the SETTINGS permission.

Status Codes:

Retrieve a list of users

GET /api/access/users

Retrieves a list of all registered users in OctoPrint.

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

Requires the SETTINGS permission.

Status Codes:

Retrieve a user

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

Retrieves information about a user.

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

Requires either the SETTINGS permission or to be logged in as the user.

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

Add a new user

POST /api/access/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 the SETTINGS permission.

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/access/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 the SETTINGS permission.

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/access/users/(string: username)

Delete a user record.

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

Requires the SETTINGS permission.

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

Change a user’s password

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

Changes the password of a user.

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

Requires the SETTINGS permission 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:

Get a user’s settings

GET /api/access/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 the SETTINGS permission 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/access/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 the SETTINGS permission 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 api key

POST /api/access/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 the SETTINGS permission 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 api key

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

Deletes a user’s personal API key.

Requires the SETTINGS permission or to be logged in as the user.

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

Data model

Permissions

Permission list response

Name Multiplicity Type Description
permissions 0..n List of permission records The list of permissions

Groups

Group list response

Name Multiplicity Type Description
groups 0..n List of group records The list of groups

Group registration request

Name Multiplicity Type Description
key 1 string The group’s identifier
name 1 string The group’s name
description 0..1 string The group’s description. Set to empty if not provided.
permissions 1..n List of string A list of identifier’s of permissions to assign to the group
subgroups 0..n List of string A list of identifier’s of groups to assign to the group as subgroups
default 0..1 boolean Whether to assign the group to new users by default (true) or not (false, default value)

Group update request

Name Multiplicity Type Description
description 0..1 string The group’s description. Set to empty if not provided.
permissions 1..n List of string A list of identifier’s of permissions to assign to the group
subgroups 0..n List of string A list of identifier’s of groups to assign to the group as subgroups
default 0..1 boolean Whether to assign the group to new users by default (true) or not (false, default value)

Users

User list response

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

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)
groups 0..n List of string A list of identifiers of groups to assign to the user
permissions 0..n List of string A list of identifiers of permissions to assign to the user

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.
groups 0..n List of string A list of identifiers of groups to assign to the user
permissions 0..n List of string A list of identifiers of permissions to assign to the user