((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 (@ (class . "external") (href . "https://tools.ietf.org/html/rfc7617")) "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 (@ (class . "external") (href . "https://curl.haxx.se/")) "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."))))