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 via an API-Key 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.
New in version 1.8.3.
To protect OctoPrint against CSRF attacks against the non CORS affected upload endpoints, in case of browser session based authorization the API
is protected using the Double Submit Cookie mitigation strategy.
On first page load of the UI, the login page or the recovery page, a
csrf_token_P<port>_R<root> cookie is set
and rely on cookie based authorization (so not on an API key but rather an active login session) are required
to send both the
csrf_token cookie as well as an
X-CSRF-Token header containing its value.
If you use the JS Client library, this will take care of doing the needful for you. Any code in the Core UI calling
API functions through
$.post will also take care of this for you. If you use another library for
accessing OctoPrint’s API in a browser context, you’ll need to make sure to send the
X-CSRF-Token header yourself. Examples for
several JS frameworks can be found in the OWASP cheatsheet on CSRF attacks.
Take a look at the implementations of
for details on how to retrieve the cookie value and how to construct the header.
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.