General information

Authorization

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 if “Access Control” is enabled or an ref:App Session Key <sec-api-apps-sessionkey>. Users are able to generate and revoke their custom API key via the “Change password” dialog.

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...

If it is missing or included but invalid, OctoPrint will directly return a response with status 401 Unauthorized.

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.

Global API key in the API settings

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

User specific API key location in user list

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

API key options in "Change password" dialog

Fig. 5 The API key options in the “Change password” dialog. Users can generate and revoke their custom API key here.

Note

OctoPrint’s web interface uses a custom API key that is freshly generated on every server start. This key is not intended to be used by any other client and would not be very useful in any case, since it basically represents a completely anonymous client.

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
CORS configuration in the API settings

Fig. 6 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.