Access control

Contents

• Access control

  • Permissions

    • List all permissions

  • Groups

    • Get group list

    • Add a new group

    • Retrieve a group

    • Update a group

    • Delete a group

  • Users

  • Retrieve a list of users

    • Retrieve a user

    • Add a new user

    • Update a user

    • Delete a user

    • Change a user’s password

    • Get a user’s settings

    • Update a user’s settings

    • Regenerate a user’s api key

    • Delete a user’s api key

  • Data model

    • Permissions

      • Permission list response

    • Groups

      • Group list response

      • Group registration request

      • Group update request

    • Users

      • User list response

      • User registration request

      • User update request

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

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 property password containing the new password as request body. Without the SETTINGS permission, an additional property current is also required to be set on the request body, containing the user’s current password.

Requires the SETTINGS permission or to be logged in as the user. Note that current will be evaluated even in presence of the SETTINGS permission, if set.

Parameters

• username – Name of the user to change the password for

JSON Parameters

• password – The new password to set

• current – The current password

Status Codes

• 200 OK – No error

• 400 Bad Request – If the request doesn’t contain a password property, doesn’t contain a current property even though required, or the request is otherwise invalid

• 403 Forbidden – No admin rights, not logged in as the user or a current password mismatch

• 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