101 lines
3.1 KiB
ReStructuredText
101 lines
3.1 KiB
ReStructuredText
.. _sec-api-general:
|
|
|
|
*******************
|
|
General information
|
|
*******************
|
|
|
|
.. contents::
|
|
|
|
.. _sec-api-general-authorization:
|
|
|
|
Authorization
|
|
=============
|
|
|
|
OctoPrint's API expects an API key to be supplied with each request. This API key can be either the globally
|
|
configured one or a user specific one if "Access Control" is enabled. 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.
|
|
|
|
.. sourcecode:: http
|
|
|
|
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 :http:statuscode:`401`.
|
|
|
|
For testing purposes it is also possible to supply the API key via a query parameter ``apikey``, e.g.
|
|
|
|
.. sourcecode:: http
|
|
|
|
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.
|
|
|
|
.. _fig-api-general-globalapikey:
|
|
.. figure:: ../images/settings-global-api-key.png
|
|
:align: center
|
|
:alt: Global API key in the API settings
|
|
|
|
The global API key can be found in the "API" settings
|
|
|
|
.. _fig-api-general-userapikey:
|
|
.. figure:: ../images/settings-user-api-key.png
|
|
:align: center
|
|
:alt: User specific API key location in user list
|
|
|
|
The user list in the "Access Control" settings shows the API key for users (if available)
|
|
|
|
.. _fig-api-general-changepassword:
|
|
.. figure:: ../images/change-password-api-key.png
|
|
:align: center
|
|
:alt: API key options in "Change password" dialog
|
|
|
|
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.
|
|
|
|
.. _sec-api-general-contenttype:
|
|
|
|
Content Type
|
|
============
|
|
|
|
If not otherwise stated OctoPrint's API expects request bodies and issues response bodies as ``Content-Type: application/json``.
|
|
|
|
.. _sec-api-general-encoding:
|
|
|
|
Encoding
|
|
========
|
|
|
|
OctoPrint uses UTF-8 as charset.
|
|
|
|
|
|
.. _sec-api-cross-origin:
|
|
|
|
Cross-origin requests
|
|
===================
|
|
To make use of the Octoprint API from websites other than the Octoprint web interface,
|
|
cross-origin resource sharing (`CORS <http://en.wikipedia.org/wiki/Cross-origin_resource_sharing>`) 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 in ``config.yml`` to ``true``.
|
|
|
|
.. code-block:: yaml
|
|
|
|
api:
|
|
enabled: true
|
|
key: MYKEY
|
|
allowCrossOrigin: true
|
|
|
|
.. 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 similar to:
|
|
|
|
``XMLHttpRequest cannot load http://localhost:8081/api/files. No 'Access-Control-Allow-Origin' header is present on the requested resource.``
|
|
|