((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."))))