General information¶
Contents
Authorization¶
If Access Control is enabled OctoPrint’s API expects an API key to be supplied with each request. This API key can be either the globally configured one, a user specific one or an app and user specific one as generated by the authorization workflow implemented by the bundled Application Keys Plugin (since 1.3.10).
Clients are advised to implement the Application Keys Plugin workflow first and fallback on directing the user to manually supply the the user specific API key. The global key should rarely be used.
The API key must be supplied in the custom HTTP header X-Api-Key
, e.g.
GET /api/files HTTP/1.1
Host: example.com
X-Api-Key: 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. Consequently, if the bundled ForceLogin plugin is active (which is the default), 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!
Note
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.

Fig. 22 The global API key can be found in the “API” settings

Fig. 23 The user list in the “Access Control” settings shows the API key for users (if available)

Fig. 24 The API key options in the “Change password” dialog. Users can generate and revoke their custom API key here.
Content Type¶
If not otherwise stated, OctoPrint’s API expects request bodies and issues response bodies as Content-Type: application/json
.
Encoding¶
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.
Cross-origin requests¶
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

Fig. 25 Support for CORS can be enabled in the “API” settings
Note
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.
Login¶
-
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 401 Unauthorized in case of a username/password mismatch or unknown user and a 403 Forbidden in case of a deactivated account.
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
- 401 Unauthorized – Username/password mismatch or unknown user
- 403 Forbidden – Deactivated account
Logout¶
-
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
Data model¶
Login response¶
Name | Multiplicity | Type | Description |
---|---|---|---|
name |
1 | string | the user’s name/id |
active |
1 | boolean | Whether the user’s account is active or not |
admin |
1 | boolean | Whether the user has admin rights or not |
user |
1 | boolean | Whether the user has user rights or not (always true ) |
apikey |
1 | string or None | The user’s API key, if set |
settings |
1 | dict | The user’s settings, if any |
session |
1 | string | The session key, can be used to authenticate with the auth message on the push API. |
_is_external_client |
1 | boolean | Whether the client that made the request got detected as external from the local network or not. |