((META (EMPTY-STRING title "API: Check for authentication") (WORD role "manual") (TAG-SET tags ("#api" "#manual" "#zettelstore")) (WORD syntax "zmk") (ZID-SET back ("00001012000000" "00001012080100")) (ZID-SET backward ("00001012000000" "00001012080100")) (NUMBER box-number "1") (STRING copyright "(c) 2020-present by Detlef Stern <ds@zettelstore.de>") (TIMESTAMP created "20220103224858") (ZID-SET forward ("00001010040100" "00001012050200" "00001012920000")) (WORD lang "en") (EMPTY-STRING license "EUPL-1.2-or-later") (TIMESTAMP modified "20220908163156") (TIMESTAMP published "20220908163156") (WORD visibility "public")) (BLOCK (PARA (TEXT "API clients typically wants to know, whether ") (LINK-ZETTEL () "00001010040100" (TEXT "authentication is enabled")) (TEXT " or not.") (SOFT) (TEXT "If authentication is enabled, they present some form of user interface to get user name and password for the actual authentication.") (SOFT) (TEXT "Then they try to ") (LINK-ZETTEL () "00001012050200" (TEXT "obtain an access token")) (TEXT ".") (SOFT) (TEXT "If authentication is disabled, these steps are not needed.")) (PARA (TEXT "To check for enabled authentication, you must send a HTTP POST request to the ") (LINK-ZETTEL () "00001012920000" (TEXT "endpoint")) (TEXT " ") (LITERAL-INPUT () "/x") (TEXT " and you must specify the query parameter ") (LITERAL-INPUT () "cmd=authenticated") (TEXT ".")) (VERBATIM-CODE (("" . "sh")) "# curl -X POST 'http://127.0.0.1:23123/x?cmd=authenticated'") (PARA (TEXT "If authentication is not enabled, you will get a HTTP status code 200 (OK) with an empty HTTP body.")) (PARA (TEXT "Otherwise, authentication is enabled.") (SOFT) (TEXT "If you provide a valid access token, you will receive a HTTP status code 204 (No Content) with an empty HTTP body.") (SOFT) (TEXT "If you did not provide a valid access token (with is the typical case), you will get a HTTP status code 401 (Unauthorized), again with an empty HTTP body.")) (HEADING 1 () "http-status-codes" "http-status-codes" (TEXT "HTTP Status codes")) (DESCRIPTION ((LITERAL-INPUT () "200")) (BLOCK (BLOCK (PARA (TEXT "Authentication is disabled.")))) ((LITERAL-INPUT () "204")) (BLOCK (BLOCK (PARA (TEXT "Authentication is enabled and a valid access token was provided.")))) ((LITERAL-INPUT () "400")) (BLOCK (BLOCK (PARA (TEXT "Request was not valid.") (HARD) (TEXT "There are several reasons for this.") (SOFT) (TEXT "Most likely, no query parameter ") (LITERAL-INPUT () "cmd") (TEXT " was given, or it did not contain the value ") (FORMAT-QUOTE () (TEXT "authenticate")) (TEXT ".")))) ((LITERAL-INPUT () "401")) (BLOCK (BLOCK (PARA (TEXT "Authentication is enabled and not valid access token was provided.")))))))