(zettel (meta (back "00001012000000 00001012080100") (backward "00001012000000 00001012080100") (box-number "1") (created "20220103224858") (forward "00001010040100 00001012050200 00001012920000") (modified "20220908163156") (published "20220908163156") (role "manual") (syntax "zmk") (tags "#api #manual #zettelstore") (title "API: Check for authentication")) (rights 4) (encoding "") (content "API clients typically wants to know, whether [[authentication is enabled|00001010040100]] or not.\nIf authentication is enabled, they present some form of user interface to get user name and password for the actual authentication.\nThen they try to [[obtain an access token|00001012050200]].\nIf authentication is disabled, these steps are not needed.\n\nTo check for enabled authentication, you must send a HTTP POST request to the [[endpoint|00001012920000]] ''/x'' and you must specify the query parameter ''cmd=authenticated''.\n\n```sh\n# curl -X POST 'http://127.0.0.1:23123/x?cmd=authenticated'\n```\n\nIf authentication is not enabled, you will get a HTTP status code 200 (OK) with an empty HTTP body.\n\nOtherwise, authentication is enabled.\nIf you provide a valid access token, you will receive a HTTP status code 204 (No Content) with an empty HTTP body.\nIf 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.\n\n=== HTTP Status codes\n; ''200''\n: Authentication is disabled.\n; ''204''\n: Authentication is enabled and a valid access token was provided.\n; ''400''\n: Request was not valid. \n  There are several reasons for this.\n  Most likely, no query parameter ''cmd'' was given, or it did not contain the value \"\"authenticate\"\".\n; ''401''\n: Authentication is enabled and not valid access token was provided."))