diff --git a/doc/api/auth.rst b/doc/api/auth.rst new file mode 100644 index 000000000..4becd60d4 --- /dev/null +++ b/doc/api/auth.rst @@ -0,0 +1,9 @@ +Authentication +============== + +.. toctree:: + :maxdepth: 2 + + tokenauth + oauth + deviceauth diff --git a/doc/api/deviceauth.rst b/doc/api/deviceauth.rst new file mode 100644 index 000000000..52f784afc --- /dev/null +++ b/doc/api/deviceauth.rst @@ -0,0 +1,127 @@ +.. _`rest-deviceauth`: + +Device authentication +===================== + +Initializing a new device +------------------------- + +Users can create new devices in the "Device" section of their organizer settings. When creating +a new device, users can specify a list of events the device is allowed to access. After a new +device is created, users will be presented initialization instructions, consisting of an URL +and an initialization token. They will also be shown as a QR code with the following contents:: + + {"handshake_version": 1, "url": "https://pretix.eu", "token": "kpp4jn8g2ynzonp6"} + +Your application should be able to scan a QR code of this type, or allow to enter the URL and the +initialization token manually. The handshake version is not used for manual initialization. When a +QR code is scanned with a higher handshake version than you support, you should reject the request +and prompt the user to update the client application. + +After your application received the token, you need to call the initialization endpoint to obtain +a proper API token. At this point, you need to identify the name and version of your application, +as well as the type of underlying hardware. Example: + +.. sourcecode:: http + + POST /api/v1/device/initialize HTTP/1.1 + Host: pretix.eu + Content-Type: application/json + + { + "token": "kpp4jn8g2ynzonp6", + "hardware_brand": "Samsung", + "hardware_model": "Galaxy S", + "software_brand": "pretixdroid", + "software_version": "4.0.0" + } + +Every initialization token can only be used once. On success, you will receive a response containing +information on your device as well as your API token: + +.. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "organizer": "foo", + "device_id": 5, + "unique_serial": "HHZ9LW9JWP390VFZ", + "api_token": "1kcsh572fonm3hawalrncam4l1gktr2rzx25a22l8g9hx108o9oi0rztpcvwnfnd", + "name": "Bar" + } + +Please make sure that you store this ``api_token`` value. We also recommend storing your device ID, your assigned +``unique_serial``, and the ``organizer`` you have access to, but that's up to you. + +In case of an error, the response will look like this: + +.. sourcecode:: http + + HTTP/1.1 400 Bad Request + Content-Type: application/json + + {"token":["This initialization token has already been used."]} + + +Performing API requests +----------------------- + +You need to include the API token with every request to pretix' API in the ``Authorization`` header +like the following: + +.. sourcecode:: http + :emphasize-lines: 3 + + GET /api/v1/organizers/ HTTP/1.1 + Host: pretix.eu + Authorization: Device 1kcsh572fonm3hawalrncam4l1gktr2rzx25a22l8g9hx108o9oi0rztpcvwnfnd + +Updating the software version +----------------------------- + +If your application is updated, we ask you to tell the server about the new version in use. You can do this at the +following endpoint: + +.. sourcecode:: http + + POST /api/v1/device/update HTTP/1.1 + Host: pretix.eu + Content-Type: application/json + Authorization: Device 1kcsh572fonm3hawalrncam4l1gktr2rzx25a22l8g9hx108o9oi0rztpcvwnfnd + + { + "hardware_brand": "Samsung", + "hardware_model": "Galaxy S", + "software_brand": "pretixdroid", + "software_version": "4.1.0" + } + +Creating a new API key +---------------------- + +If you think your API key might have leaked or just want to be extra cautious, the API allows you to create a new key. +The old API key will be invalid immediately. A request for a new key looks like this: + +.. sourcecode:: http + + POST /api/v1/device/roll HTTP/1.1 + Host: pretix.eu + Authorization: Device 1kcsh572fonm3hawalrncam4l1gktr2rzx25a22l8g9hx108o9oi0rztpcvwnfnd + +The response will look like the response to the initialization request. + +Removing a device +----------------- + +If you want implement a way to to deprovision a device in your software, you can call the ``revoke`` endpoint to +invalidate your API key. There is no way to reverse this operation. + +.. sourcecode:: http + + POST /api/v1/device/revoke HTTP/1.1 + Host: pretix.eu + Authorization: Device 1kcsh572fonm3hawalrncam4l1gktr2rzx25a22l8g9hx108o9oi0rztpcvwnfnd + +This can also be done by the user through the web interface. diff --git a/doc/api/fundamentals.rst b/doc/api/fundamentals.rst index fbb86e41a..7a297ab1f 100644 --- a/doc/api/fundamentals.rst +++ b/doc/api/fundamentals.rst @@ -9,44 +9,20 @@ with pretix' REST API, such as authentication, pagination and similar definition Authentication -------------- -If you're building an application for end users, we strongly recommend that you use our -:ref:`OAuth-based authentication progress `. However, for simpler needs, you -can also go with static API tokens that you can create on a per-team basis (see below). +To access the API, you need to present valid authentication credentials. pretix currently +supports the following authorization schemes: -You need to include the API token with every request to pretix' API in the ``Authorization`` header -like the following: - -.. sourcecode:: http - :emphasize-lines: 3 - - GET /api/v1/organizers/ HTTP/1.1 - Host: pretix.eu - Authorization: Token e1l6gq2ye72thbwkacj7jbri7a7tvxe614ojv8ybureain92ocub46t5gab5966k - -.. note:: The API currently also supports authentication via browser sessions, i.e. the - same way that you authenticate with pretix when using the browser interface. - Using this type of authentication is *not* officially supported for use by - third-party clients and might change or be removed at any time. We plan on - adding OAuth2 support in the future for user-level authentication. If you want - to use session authentication, be sure to comply with Django's `CSRF policies`_. - -Obtaining an API token ----------------------- - -To authenticate your API requests, you need to obtain an API token. You can create a -token in the pretix web interface on the level of organizer teams. Create a new team -or choose an existing team that has the level of permissions the token should have and -create a new token using the form below the list of team members: - -.. image:: img/token_form.png - :class: screenshot - -You can enter a description for the token to distinguish from other tokens later on. -Once you click "Add", you will be provided with an API token in the success message. -Copy this token, as you won't be able to retrieve it again. - -.. image:: img/token_success.png - :class: screenshot +* :ref:`rest-tokenauth`: This is the simplest way and recommended for server-side applications + that interact with pretix without user interaction. +* :ref:`rest-oauth`: This is the recommended way to use if you write a third-party application + that users can connect with their pretix account. It provides the best user experience, but + requires user interaction and slightly more implementation effort. +* :ref:`rest-deviceauth`: This is the recommended way if you build apps or hardware devices that can + connect to pretix, e.g. for processing check-ins or to sell tickets offline. It provides a way + to uniquely identify devices and allows for a quick configuration flow inside your software. +* Authentication using browser sessions: This is used by the pretix web interface and it is *not* + officially supported for use by third-party applications. It might change or be removed at any + time without prior notice. If you use it, you need to comply with Django's `CSRF policies`_. Permissions ----------- @@ -204,4 +180,4 @@ as the string values ``true`` and ``false``. If the ``ordering`` parameter is documented for a resource, you can use it to sort the result set by one of the allowed fields. Prepend a ``-`` to the field name to reverse the sort order. -.. _CSRF policies: https://docs.djangoproject.com/en/1.11/ref/csrf/#ajax \ No newline at end of file +.. _CSRF policies: https://docs.djangoproject.com/en/1.11/ref/csrf/#ajax diff --git a/doc/api/index.rst b/doc/api/index.rst index 0e8ace9c4..9d5302ec0 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -14,5 +14,5 @@ in functionality over time. :maxdepth: 2 fundamentals - oauth + auth resources/index diff --git a/doc/api/oauth.rst b/doc/api/oauth.rst index 21b972cd4..770227e6c 100644 --- a/doc/api/oauth.rst +++ b/doc/api/oauth.rst @@ -1,7 +1,7 @@ .. _`rest-oauth`: -OAuth support / "Connect with pretix" -===================================== +OAuth authentication / "Connect with pretix" +============================================ In addition to static tokens, pretix supports `OAuth2`_-based authentication starting with pretix 1.16. This allows you to put a "Connect with pretix" button into your website or tool @@ -168,4 +168,4 @@ pretix user interface. .. _OAuth2: https://en.wikipedia.org/wiki/OAuth .. _OAuth2 Simplified: https://aaronparecki.com/oauth-2-simplified/ -.. _HTTP Basic authentication: https://en.wikipedia.org/wiki/Basic_access_authentication \ No newline at end of file +.. _HTTP Basic authentication: https://en.wikipedia.org/wiki/Basic_access_authentication diff --git a/doc/api/tokenauth.rst b/doc/api/tokenauth.rst new file mode 100644 index 000000000..7f430a166 --- /dev/null +++ b/doc/api/tokenauth.rst @@ -0,0 +1,36 @@ +.. _`rest-tokenauth`: + +Token-based authentication +========================== + +Obtaining an API token +---------------------- + +To authenticate your API requests with Tokens, you need to obtain a team-level API token. +You can create a token in the pretix web interface on the level of organizer teams. Create +a new team or choose an existing team that has the level of permissions the token should +have and create a new token using the form below the list of team members: + +.. image:: img/token_form.png + :class: screenshot + +You can enter a description for the token to distinguish from other tokens later on. +Once you click "Add", you will be provided with an API token in the success message. +Copy this token, as you won't be able to retrieve it again. + +.. image:: img/token_success.png + :class: screenshot + +Using an API token +------------------ + +You need to include the API token with every request to pretix' API in the ``Authorization`` header +like the following: + +.. sourcecode:: http + :emphasize-lines: 3 + + GET /api/v1/organizers/ HTTP/1.1 + Host: pretix.eu + Authorization: Token e1l6gq2ye72thbwkacj7jbri7a7tvxe614ojv8ybureain92ocub46t5gab5966k + diff --git a/doc/spelling_wordlist.txt b/doc/spelling_wordlist.txt index b6e975c82..ed90ba67f 100644 --- a/doc/spelling_wordlist.txt +++ b/doc/spelling_wordlist.txt @@ -23,6 +23,7 @@ cronjob cryptographic debian deduplication +deprovision discoverable django dockerfile