desec-stack/docs/endpoint-reference.rst

.. _endpoint-reference:

Endpoint Reference
------------------

The following table summarizes basic information about the deSEC API endpoints used
for :ref:`managing users <manage-account>` and :ref:`tokens <manage-tokens>`.

+------------------------------------------------------+------------+---------------------------------------------+
| Endpoint ``/api/v1``...                              | Methods    | Use case                                    |
+======================================================+============+=============================================+
| ...\ ``/auth/``                                      | ``POST``   | Register user account                       |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/auth/account/``                              | ``GET``    | Retrieve user account information           |
+                                                      +------------+---------------------------------------------+
|                                                      | ``PATCH``  | Modify user account settings                |
+                                                      +------------+---------------------------------------------+
|                                                      | ``PUT``    | Replace user account settings               |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/auth/account/change-email/``                 | ``POST``   | Request account email address change        |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/auth/account/reset-password/``               | ``POST``   | Request password reset                      |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/auth/account/delete/``                       | ``POST``   | Request account deletion                    |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/auth/login/``                                | ``POST``   | Log in and request authentication token     |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/auth/logout/``                               | ``POST``   | Log out (= delete current token)            |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/auth/tokens/``                               | ``GET``    | Retrieve all current tokens                 |
|                                                      +------------+---------------------------------------------+
|                                                      | ``POST``   | Create new token                            |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/auth/tokens/{id}/``                          | ``GET``    | Retrieve token                              |
|                                                      +------------+---------------------------------------------+
|                                                      | ``DELETE`` | Delete token                                |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/auth/tokens/{id}/policies/rrsets/``          | ``GET``    | Retrieve all RRset policies for the given   |
|                                                      |            | token                                       |
|                                                      +------------+---------------------------------------------+
|                                                      | ``POST``   | Create an RRset policy for the given token  |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/auth/tokens/{id}/policies/rrsets/{policy}/`` | ``GET``    | Retrieve a specific token RRset policy      |
|                                                      +------------+---------------------------------------------+
|                                                      | ``PATCH``  | Modify a token policy                       |
|                                                      +------------+---------------------------------------------+
|                                                      | ``PUT``    | Replace a token policy                      |
|                                                      +------------+---------------------------------------------+
|                                                      | ``DELETE`` | Delete a token policy                       |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/auth/totp/``                                 |            | 2FA-related, interface subject to change    |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/captcha/``                                   | ``POST``   | Obtain captcha                              |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/v/activate-account/{code}/``                 | ``POST``   | Confirm email address for new account       |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/v/reset-password/{code}/``                   | ``POST``   | Confirm password reset                      |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/v/change-email/{code}/``                     | ``POST``   | Confirm email address change                |
+------------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/v/delete-account/{code}/``                   | ``POST``   | Confirm account deletion                    |
+------------------------------------------------------+------------+---------------------------------------------+

The following table summarizes basic information about the deSEC API endpoints used
for :ref:`domain-management` and :ref:`Retrieving and Manipulating DNS
Information <manage-rrsets>`.

+------------------------------------------------+------------+---------------------------------------------+
| Endpoint ``/api/v1/domains``...                | Methods    | Use case                                    |
+================================================+============+=============================================+
| ...\ ``/``                                     | ``GET``    | Retrieve all domains you own                |
|                                                +------------+---------------------------------------------+
|                                                | ``POST``   | Create a domain                             |
+------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/{name}/``                              | ``GET``    | Retrieve a specific domain                  |
|                                                +------------+---------------------------------------------+
|                                                | ``PATCH``  | Modify a domain (deprecated)                |
|                                                +------------+---------------------------------------------+
|                                                | ``DELETE`` | Delete a domain                             |
+------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/{name}/rrsets/``                       | ``GET``    | Retrieve all RRsets from ``domain``, filter |
|                                                |            | by ``subname`` or ``type`` query parameter  |
|                                                +------------+---------------------------------------------+
|                                                | ``POST``   | Create one or more RRsets                   |
|                                                +------------+---------------------------------------------+
|                                                | ``PATCH``  | Create, modify or delete one or more RRsets |
|                                                +------------+---------------------------------------------+
|                                                | ``PUT``    | Create, modify or delete one or more RRsets |
+------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/{name}/rrsets/@/{type}/``              |            | Access an RRset at the zone apex            |
+------------------------------------------------+------------+---------------------------------------------+
| ...\ ``/{name}/rrsets/{subname}/{type}/``      | ``GET``    | Retrieve a specific RRset                   |
|                                                +------------+---------------------------------------------+
| ...\ ``/{name}/rrsets/{subname}.../{type}/``   | ``PATCH``  | Modify an RRset                             |
|                                                +------------+---------------------------------------------+
|                                                | ``PUT``    | Replace an RRset                            |
|                                                +------------+---------------------------------------------+
|                                                | ``DELETE`` | Delete an RRset                             |
+------------------------------------------------+------------+---------------------------------------------+