2013-12-15 17:45:38 +00:00
|
|
|
.. _sec-api-general:
|
|
|
|
|
|
|
|
|
|
*******************
|
|
|
|
|
General information
|
|
|
|
|
*******************
|
|
|
|
|
|
2013-12-21 12:01:18 +00:00
|
|
|
.. contents::
|
|
|
|
|
|
2013-12-15 17:45:38 +00:00
|
|
|
.. _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
|
2013-12-16 00:47:06 +00:00
|
|
|
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.
|
2013-12-15 17:45:38 +00:00
|
|
|
|
2013-12-16 00:47:06 +00:00
|
|
|
The API key must be supplied in the custom HTTP header ``X-Api-Key``, e.g.
|
2013-12-15 17:45:38 +00:00
|
|
|
|
|
|
|
|
.. sourcecode:: http
|
|
|
|
|
|
2013-12-16 00:47:06 +00:00
|
|
|
GET /api/files HTTP/1.1
|
2013-12-15 17:45:38 +00:00
|
|
|
Host: example.com
|
2013-12-16 00:47:06 +00:00
|
|
|
X-Api-Key: abcdef...
|
2013-12-15 17:45:38 +00:00
|
|
|
|
2013-12-21 12:01:18 +00:00
|
|
|
If it is missing or included but invalid, OctoPrint will directly return a response with status :http:statuscode:`401`.
|
2013-12-16 00:47:06 +00:00
|
|
|
|
|
|
|
|
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.
|
2013-12-15 17:45:38 +00:00
|
|
|
|
|
|
|
|
.. _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.
|
|
|
|
|
|
2013-12-16 00:47:06 +00:00
|
|
|
.. _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.
|
