Access control ¶

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:	200 OK – No error

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:	200 OK – No error

Users ¶

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:	200 OK – No error

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:	200 OK – No error 404 Not Found – Unknown user

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.

JSON Parameters:
Parameters:	username – Name of the user to update
	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:	200 OK – No error 404 Not Found – Unknown user

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:	200 OK – No error 404 Not Found – Unknown user

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.

JSON Parameters:
Parameters:	username – Name of the user to change the password for
	password – The new password to set
Status Codes:	200 OK – No error 400 Bad Request – If the request doesn’t contain a `password` property or the request is otherwise invalid 403 Forbidden – No admin rights and not logged in as the user 404 Not Found – The user is unknown

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:	200 OK – No error 403 Forbidden – No admin rights and not logged in as the user 404 Not Found – The user is unknown

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:	204 No Content – No error 403 Forbidden – No admin rights and not logged in as the user 404 Not Found – The user is unknown

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:	200 OK – No error 403 Forbidden – No admin rights and not logged in as the user 404 Not Found – The user is unknown

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:	204 No Content – No error 403 Forbidden – No admin rights and not logged in as the user 404 Not Found – The user is unknown

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