(BLOCK (PARA (TEXT "Authentication for future API calls is done by sending a ") (LINK-ZETTEL () "00001010040200" (TEXT "user identification")) (TEXT " and a password to the Zettelstore to obtain an ") (LINK-ZETTEL () "00001010040700" (TEXT "access token")) (TEXT ".") (SOFT) (TEXT "This token has to be used for other API calls.") (SOFT) (TEXT "It is valid for a relatively short amount of time, as configured with the key ") (LITERAL-INPUT () "token-lifetime-api") (TEXT " of the ") (LINK-ZETTEL () "00001004010000#token-lifetime-api" (TEXT "startup configuration")) (TEXT " (typically 10 minutes).")) (PARA (TEXT "The simplest way is to send user identification (") (LITERAL-INPUT () "IDENT") (TEXT ") and password (") (LITERAL-INPUT () "PASSWORD") (TEXT ") via ") (LINK-EXTERNAL () "https://tools.ietf.org/html/rfc7617" (TEXT "HTTP Basic Authentication")) (TEXT " and send them to the ") (LINK-ZETTEL () "00001012920000" (TEXT "endpoint")) (TEXT " ") (LITERAL-INPUT () "/a") (TEXT " with a POST request:")) (VERBATIM-CODE (("" . "sh")) "# curl -X POST -u IDENT:PASSWORD http://127.0.0.1:23123/a\n(\"Bearer\" \"eyJhbGciOiJIUzUxMiJ9.eyJfdGsiOjEsImV4cCI6MTY4MTMwNDA2MiwiaWF0IjoxNjgxMzA0MDAyLCJzdWIiOiJvd25lciIsInppZCI6IjIwMjEwNjI5MTYzMzAwIn0.kdF8PdiL50gIPkRD3ovgR6nUXR0-80EKAXcY2zVYgYvryF09iXnNR3zrvYnGzdrArMcnvAYqVvuXtqhQj2jG9g\" 600)") (PARA (TEXT "Some tools, like ") (LINK-EXTERNAL () "https://curl.haxx.se/" (TEXT "curl")) (TEXT ", also allow to specify user identification and password as part of the URL:")) (VERBATIM-CODE (("" . "sh")) "# curl -X POST http://IDENT:PASSWORD@127.0.0.1:23123/a\n(\"Bearer\" \"eyJhbGciOiJIUzUxMiJ9.eyJfdGsiOjEsImV4cCI6MTY4MTMwNDA4NiwiaWF0IjoxNjgxMzA0MDI2LCJzdWIiOiJvd25lciIsInppZCI6IjIwMjEwNjI5MTYzMzAwIn0.kZd3prYc79dt9efDsrYVHtKrjWyOWvfByjeeUB3hf_vs43V3SNJqmb8k-zTHVNWOK0-5orVPrg2tIAqbXqmkhg\" 600)") (PARA (TEXT "If you do not want to use Basic Authentication, you can also send user identification and password as HTML form data:")) (VERBATIM-CODE (("" . "sh")) "# curl -X POST -d 'username=IDENT&password=PASSWORD' http://127.0.0.1:23123/a\n(\"Bearer\" \"eyJhbGciOiJIUzUxMiJ9.eyJfdGsiOjEsImV4cCI6MTY4MTMwNDA4OCwiaWF0IjoxNjgxMzA0MDI4LCJzdWIiOiJvd25lciIsInppZCI6IjIwMjEwNjI5MTYzMzAwIn0.qIEyOMFXykCApWtBaqbSESwTL96stWl2LRICiRNAXUjcY-mwx_SSl9L5Fj2FvmrI1K1RBvWehjoq8KZUNjhJ9Q\" 600)") (PARA (TEXT "In all cases, you will receive a list with three elements that will contain all ") (LINK-ZETTEL () "00001012921000" (TEXT "relevant data")) (TEXT " to be used for further API calls.")) (PARA (FORMAT-STRONG () (TEXT "Important:")) (TEXT " obtaining a token is a time-intensive process.") (SOFT) (TEXT "Zettelstore will delay every request to obtain a token for a certain amount of time.") (SOFT) (TEXT "Please take into account that this request will take approximately 500 milliseconds, under certain circumstances more.")) (PARA (TEXT "However, if ") (LINK-ZETTEL () "00001010040100" (TEXT "authentication is not enabled")) (TEXT " and you send an authentication request, no user identification/password checking is done and you receive an artificial token immediate, without any delay:")) (VERBATIM-CODE (("" . "sh")) "# curl -X POST -u IDENT:PASSWORD http://127.0.0.1:23123/a\n(\"Bearer\" \"freeaccess\" 316224000)") (PARA (TEXT "In this case, it is even possible to omit the user identification/password.")) (HEADING 1 () "http-status-codes" "http-status-codes" (TEXT "HTTP Status codes")) (PARA (TEXT "In all cases of successful authentication, a list is returned, which contains the token as the second element.") (SOFT) (TEXT "A successful authentication is signaled with the HTTP status code 200, as usual.")) (PARA (TEXT "Other status codes possibly send by the Zettelstore:")) (DESCRIPTION ((LITERAL-INPUT () "400")) (BLOCK (BLOCK (PARA (TEXT "Unable to process the request.") (SOFT) (TEXT "In most cases the form data was invalid.")))) ((LITERAL-INPUT () "401")) (BLOCK (BLOCK (PARA (TEXT "Authentication failed.") (SOFT) (TEXT "Either the user identification is invalid or you provided the wrong password.")))) ((LITERAL-INPUT () "403")) (BLOCK (BLOCK (PARA (TEXT "Authentication is not active."))))))