Access control¶
Contents
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
200 OK – No error
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
200 OK – No error
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
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
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 invalid403 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 |
---|---|---|---|
|
0..n |
List of permission records |
The list of permissions |
Groups¶
Group list response¶
Name |
Multiplicity |
Type |
Description |
---|---|---|---|
|
0..n |
List of group records |
The list of groups |
Group registration request¶
Name |
Multiplicity |
Type |
Description |
---|---|---|---|
|
1 |
string |
The group’s identifier |
|
1 |
string |
The group’s name |
|
0..1 |
string |
The group’s description. Set to empty if not provided. |
|
1..n |
List of string |
A list of identifier’s of permissions to assign to the group |
|
0..n |
List of string |
A list of identifier’s of groups to assign to the group as subgroups |
|
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 |
---|---|---|---|
|
0..1 |
string |
The group’s description. Set to empty if not provided. |
|
1..n |
List of string |
A list of identifier’s of permissions to assign to the group |
|
0..n |
List of string |
A list of identifier’s of groups to assign to the group as subgroups |
|
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 |
---|---|---|---|
|
0..n |
List of user records |
The list of users |
User registration request¶
Name |
Multiplicity |
Type |
Description |
---|---|---|---|
|
1 |
string |
The user’s name |
|
1 |
string |
The user’s password |
|
1 |
bool |
Whether to activate the account (true) or not (false) |
|
0..n |
List of string |
A list of identifiers of groups to assign to the user |
|
0..n |
List of string |
A list of identifiers of permissions to assign to the user |
User update request¶
Name |
Multiplicity |
Type |
Description |
---|---|---|---|
|
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. |
|
0..n |
List of string |
A list of identifiers of groups to assign to the user |
|
0..n |
List of string |
A list of identifiers of permissions to assign to the user |