Access control ¶

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.

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

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.

Parameters

username – Name of the user to change the password for

JSON Parameters

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