If not otherwise stated, OctoPrint’s API expects request bodies and issues response bodies as
OctoPrint uses UTF-8 as charset.
That also includes headers in
multipart/form-data requests, in order to allow the full UTF-8 range of characters
for uploaded filenames. If a
multipart/form-data sub header cannot be decoded as UTF-8, OctoPrint will also attempt
to decode it as ISO-8859-1.
Additionally, OctoPrint supports replacing the
filename field in the
Content-Disposition header of a
multipart field with a
filename* field following RFC 5987, Section 3.2,
which allows defining the charset used for encoding the filename. If both
filename* fields are
present, following the recommendation of the RFC
filename* will be used.
For an example on how to send a request utilizing RFC 5987 for the
filename* attribute, see the second example
in Upload file.
To make use of the OctoPrint API from websites other than the OctoPrint web interface, cross-origin resource sharing (CORS) must be enabled. This is the case even when the website in question is served from a different port on the same machine and on localhost.
To enable this feature, set the
allowCrossOrigin key of the
api section in
check the corresponding checkbox in the API settings dialog.
api: enabled: true key: ... allowCrossOrigin: true
This means any browser page can send requests to the OctoPrint API. Authorization is still required however.
If CORS is not enabled you will get errors like the following:
XMLHttpRequest cannot load http://localhost:8081/api/files. No 'Access-Control-Allow-Origin' header is present on the requested resource.
For security reasons, OctoPrint will not set the
header, even if CORS support is enabled. That means that cookies will not be sent by
the browser to OctoPrint, effectively making it impossible to authenticate through
the login mechanism (or reusing an existing login session). When accessing OctoPrint
via CORS, you’ll therefore always need to use an API key.
Creates a login session or retrieves information about the currently existing session (“passive login”).
Can be used in one of two ways: to login a user via username and password and create a persistent session (usually from a UI in the browser), or to retrieve information about the active user (from an existing session or an API key) via the
Will return a 200 OK with a login response on successful login, whether active or passive. The active (username/password) login may also return a 403 Forbidden in case of a username/password mismatch, unknown user or a deactivated account.
Previous versions of this API endpoint did return a 401 Unauthorized in case of a username/password mismatch or an unknown user. That was incompatible with basic authentication since it was a wrong use of the 401 Unauthorized code and got therefore changed as part of a bug fix.
You cannot use this endpoint to login from a third party page via CORS, see above. You can however use it to retrieve user information via passive login with an API key (e.g. if you need the
sessionto authenticate on the web socket.
- JSON Parameters
passive – If present, performs a passive login only, returning information about the current user that’s active either through an existing session or the used API key
user – (active login only) Username
pass – (active login only) Password
remember – (active login only) Whether to set a “remember me” cookie on the session
- Status Codes
The Login response is a user record extended by the following fields:
The session key, can be used to authenticate with the
Whether the client that made the request got detected as external from the local network or not.