(((meta (@ (content . "API: Check for authentication") (name . "title"))) (meta (@ (content . "manual") (name . "role"))) (meta (@ (content . "#api #manual #zettelstore") (name . "tags"))) (meta (@ (content . "zmk") (name . "syntax"))) (meta (@ (content . "00001012000000 00001012080100") (name . "back"))) (meta (@ (content . "00001012000000 00001012080100") (name . "backward"))) (meta (@ (content . "1") (name . "box-number"))) (meta (@ (content . "(c) 2020-present by Detlef Stern <ds@zettelstore.de>") (name . "copyright"))) (meta (@ (content . "20220103224858") (name . "created"))) (meta (@ (content . "00001010040100 00001012050200 00001012920000") (name . "forward"))) (meta (@ (content . "en") (name . "lang"))) (meta (@ (content . "EUPL-1.2-or-later") (name . "license"))) (meta (@ (content . "20220908163156") (name . "modified"))) (meta (@ (content . "20220908163156") (name . "published"))) (meta (@ (content . "public") (name . "visibility")))) (p "API clients typically wants to know, whether " (a (@ (href . "00001010040100")) "authentication is enabled") " or not." " " "If authentication is enabled, they present some form of user interface to get user name and password for the actual authentication." " " "Then they try to " (a (@ (href . "00001012050200")) "obtain an access token") "." " " "If authentication is disabled, these steps are not needed.") (p "To check for enabled authentication, you must send a HTTP POST request to the " (a (@ (href . "00001012920000")) "endpoint") " " (kbd "/x") " and you must specify the query parameter " (kbd "cmd=authenticated") ".") (pre (code (@ (class . "language-sh")) "# curl -X POST 'http://127.0.0.1:23123/x?cmd=authenticated'")) (p "If authentication is not enabled, you will get a HTTP status code 200 (OK) with an empty HTTP body.") (p "Otherwise, authentication is enabled." " " "If you provide a valid access token, you will receive a HTTP status code 204 (No Content) with an empty HTTP body." " " "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.") (h2 (@ (id . "http-status-codes")) "HTTP Status codes") (dl (dt (kbd "200")) (dd (p "Authentication is disabled.")) (dt (kbd "204")) (dd (p "Authentication is enabled and a valid access token was provided.")) (dt (kbd "400")) (dd (p "Request was not valid." (br) "There are several reasons for this." " " "Most likely, no query parameter " (kbd "cmd") " was given, or it did not contain the value " (@L (@H "&ldquo;") "authenticate" (@H "&rdquo;")) ".")) (dt (kbd "401")) (dd (p "Authentication is enabled and not valid access token was provided."))))