(((meta (@ (content . "API: Authenticate a client") (name . "title"))) (meta (@ (content . "manual") (name . "role"))) (meta (@ (content . "#api #manual #zettelstore") (name . "tags"))) (meta (@ (content . "zmk") (name . "syntax"))) (meta (@ (content . "00001012000000 00001012050400 00001012050600 00001012051200 00001012051400 00001012053300 00001012053400 00001012053500 00001012053600 00001012080200") (name . "back"))) (meta (@ (content . "00001010040700 00001012000000 00001012050400 00001012050600 00001012051200 00001012051400 00001012053300 00001012053400 00001012053500 00001012053600 00001012080200 00001012920000 00001012921000") (name . "backward"))) (meta (@ (content . "1") (name . "box-number"))) (meta (@ (content . "(c) 2020-present by Detlef Stern <ds@zettelstore.de>") (name . "copyright"))) (meta (@ (content . "20210126175322") (name . "created"))) (meta (@ (content . "00001004010000 00001010040100 00001010040200 00001010040700 00001012920000 00001012921000") (name . "forward"))) (meta (@ (content . "en") (name . "lang"))) (meta (@ (content . "EUPL-1.2-or-later") (name . "license"))) (meta (@ (content . "20230412150544") (name . "modified"))) (meta (@ (content . "20230412150544") (name . "published"))) (meta (@ (content . "public") (name . "visibility")))) (p "Authentication for future API calls is done by sending a " (a (@ (href . "00001010040200")) "user identification") " and a password to the Zettelstore to obtain an " (a (@ (href . "00001010040700")) "access token") "." " " "This token has to be used for other API calls." " " "It is valid for a relatively short amount of time, as configured with the key " (kbd "token-lifetime-api") " of the " (a (@ (href . "00001004010000#token-lifetime-api")) "startup configuration") " (typically 10 minutes).") (p "The simplest way is to send user identification (" (kbd "IDENT") ") and password (" (kbd "PASSWORD") ") via " (a (@ (href . "https://tools.ietf.org/html/rfc7617") (rel . "external")) "HTTP Basic Authentication") " and send them to the " (a (@ (href . "00001012920000")) "endpoint") " " (kbd "/a") " with a POST request:") (pre (code (@ (class . "language-sh")) "# curl -X POST -u IDENT:PASSWORD http://127.0.0.1:23123/a\n(\"Bearer\" \"eyJhbGciOiJIUzUxMiJ9.eyJfdGsiOjEsImV4cCI6MTY4MTMwNDA2MiwiaWF0IjoxNjgxMzA0MDAyLCJzdWIiOiJvd25lciIsInppZCI6IjIwMjEwNjI5MTYzMzAwIn0.kdF8PdiL50gIPkRD3ovgR6nUXR0-80EKAXcY2zVYgYvryF09iXnNR3zrvYnGzdrArMcnvAYqVvuXtqhQj2jG9g\" 600)")) (p "Some tools, like " (a (@ (href . "https://curl.haxx.se/") (rel . "external")) "curl") ", also allow to specify user identification and password as part of the URL:") (pre (code (@ (class . "language-sh")) "# curl -X POST http://IDENT:PASSWORD@127.0.0.1:23123/a\n(\"Bearer\" \"eyJhbGciOiJIUzUxMiJ9.eyJfdGsiOjEsImV4cCI6MTY4MTMwNDA4NiwiaWF0IjoxNjgxMzA0MDI2LCJzdWIiOiJvd25lciIsInppZCI6IjIwMjEwNjI5MTYzMzAwIn0.kZd3prYc79dt9efDsrYVHtKrjWyOWvfByjeeUB3hf_vs43V3SNJqmb8k-zTHVNWOK0-5orVPrg2tIAqbXqmkhg\" 600)")) (p "If you do not want to use Basic Authentication, you can also send user identification and password as HTML form data:") (pre (code (@ (class . "language-sh")) "# curl -X POST -d 'username=IDENT&password=PASSWORD' http://127.0.0.1:23123/a\n(\"Bearer\" \"eyJhbGciOiJIUzUxMiJ9.eyJfdGsiOjEsImV4cCI6MTY4MTMwNDA4OCwiaWF0IjoxNjgxMzA0MDI4LCJzdWIiOiJvd25lciIsInppZCI6IjIwMjEwNjI5MTYzMzAwIn0.qIEyOMFXykCApWtBaqbSESwTL96stWl2LRICiRNAXUjcY-mwx_SSl9L5Fj2FvmrI1K1RBvWehjoq8KZUNjhJ9Q\" 600)")) (p "In all cases, you will receive a list with three elements that will contain all " (a (@ (href . "00001012921000")) "relevant data") " to be used for further API calls.") (p (strong "Important:") " obtaining a token is a time-intensive process." " " "Zettelstore will delay every request to obtain a token for a certain amount of time." " " "Please take into account that this request will take approximately 500 milliseconds, under certain circumstances more.") (p "However, if " (a (@ (href . "00001010040100")) "authentication is not enabled") " and you send an authentication request, no user identification/password checking is done and you receive an artificial token immediate, without any delay:") (pre (code (@ (class . "language-sh")) "# curl -X POST -u IDENT:PASSWORD http://127.0.0.1:23123/a\n(\"Bearer\" \"freeaccess\" 316224000)")) (p "In this case, it is even possible to omit the user identification/password.") (h2 (@ (id . "http-status-codes")) "HTTP Status codes") (p "In all cases of successful authentication, a list is returned, which contains the token as the second element." " " "A successful authentication is signaled with the HTTP status code 200, as usual.") (p "Other status codes possibly send by the Zettelstore:") (dl (dt (kbd "400")) (dd (p "Unable to process the request." " " "In most cases the form data was invalid.")) (dt (kbd "401")) (dd (p "Authentication failed." " " "Either the user identification is invalid or you provided the wrong password.")) (dt (kbd "403")) (dd (p "Authentication is not active."))))