GET /api/files HTTP/1.1
Host: example.com
X-Api-Key: abcdef...
or as a Bearer token in the Authorization header, e.g.
GET /api/files HTTP/1.1
Host: example.com
Authorization: Bearer abcdef...
For testing purposes it is also possible to supply the API key via a query parameter apikey, e.g.
GET /api/files?apikey=abcdef... HTTP/1.1
Host: example.com
Please be advised that clients should use the header field variant if at all possible.
If the key is missing or invalid, OctoPrint will treat the request as it would any unauthenticated anonymous request to the endpoint.
That means that any requests without or with an invalid API key targeting other API endpoints than Login
will be denied with a 403 Forbidden.
Warning
If Access Control is disabled, OctoPrint will treat any unauthenticated anonymous requests and thus also requests
with an invalid or outright missing API key as requests with full admin rights!
The API key requirements changed in 1.3.11. Up to that version, even if Access Control was disabled, all requests needed to
be supplied with an API Key. To make the webinterface work under these circumstances, an unauthenticated anonymous API key was injected into the
HTML page and also available on the Push API. The presence and ready availability of this unauthenticated
anonymous “UI API key” caused confusion and false alarm among users and didn’t contribute to the security of the platform in a
meaningful way, so it was finally abandoned in 1.3.11.
If not otherwise stated, OctoPrint’s API expects request bodies and issues response bodies as Content-Type: application/json.
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 and 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 config.yml to true or
check the corresponding checkbox in the API settings dialog.
api:
enabled: true
key: ...
allowCrossOrigin: true
Warning
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 Access-Control-Allow-Credentials
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> or csrf_token_P<port>_R<root> cookie is set
that can be read via client-side JavaScript. All requests towards the API that are not GET, HEAD or OPTIONS
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 $.ajax or $.get or $.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 OctoPrintClient.getCookie and OctoPrintClient.getHeaders in src/octoprint/static/js/client/base.js
for details on how to retrieve the cookie value and how to construct the header.
POST /api/login
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 passive flag.
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.
Warning
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 session to 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
200 OK – Successful login
403 Forbidden – Username/password mismatch, unknown user or deactivated account
POST /api/logout
Ends the current login session of the current user.
Only makes sense in the context of browser based workflows.
Will return a 204 No Content.
Status Codes
204 No Content – No error
GET /api/currentuser
Retrieves information about the current user.
Will return a 200 OK with a current user object
as body.
Status Codes
200 OK – No error
string
The session key, can be used to authenticate with the auth message on the push API.
_is_external_client
boolean
Whether the client that made the request got detected as external from the local network or not.
