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 and a recent credentials check.

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 and a recent credentials check.

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 and a recent credentials check.

Status Codes

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

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 and a recent credentials check.

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 and a recent credentials check.

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 and a recent credentials check.

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 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, and a recent credentials check. 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, no recent credentials check 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

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, and a recent credentials check.

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, and a recent credentials check.

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, and a recent credentials check.

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