(zettel (meta (back "00001012000000 00001012050400 00001012050600 00001012051200 00001012051400 00001012053300 00001012053400 00001012053500 00001012053600 00001012080200") (backward "00001010040700 00001012000000 00001012050400 00001012050600 00001012051200 00001012051400 00001012053300 00001012053400 00001012053500 00001012053600 00001012080200 00001012920000 00001012921000") (box-number "1") (created "20210126175322") (forward "00001004010000 00001010040100 00001010040200 00001010040700 00001012920000 00001012921000") (modified "20230412150544") (published "20230412150544") (role "manual") (syntax "zmk") (tags "#api #manual #zettelstore") (title "API: Authenticate a client")) (rights 4) (encoding "") (content "Authentication for future API calls is done by sending a [[user identification|00001010040200]] and a password to the Zettelstore to obtain an [[access token|00001010040700]].\nThis token has to be used for other API calls.\nIt is valid for a relatively short amount of time, as configured with the key ''token-lifetime-api'' of the [[startup configuration|00001004010000#token-lifetime-api]] (typically 10 minutes).\n\nThe simplest way is to send user identification (''IDENT'') and password (''PASSWORD'') via [[HTTP Basic Authentication|https://tools.ietf.org/html/rfc7617]] and send them to the [[endpoint|00001012920000]] ''/a'' with a POST request:\n```sh\n# curl -X POST -u IDENT:PASSWORD http://127.0.0.1:23123/a\n(\"Bearer\" \"eyJhbGciOiJIUzUxMiJ9.eyJfdGsiOjEsImV4cCI6MTY4MTMwNDA2MiwiaWF0IjoxNjgxMzA0MDAyLCJzdWIiOiJvd25lciIsInppZCI6IjIwMjEwNjI5MTYzMzAwIn0.kdF8PdiL50gIPkRD3ovgR6nUXR0-80EKAXcY2zVYgYvryF09iXnNR3zrvYnGzdrArMcnvAYqVvuXtqhQj2jG9g\" 600)\n```\n\nSome tools, like [[curl|https://curl.haxx.se/]], also allow to specify user identification and password as part of the URL:\n```sh\n# curl -X POST http://IDENT:PASSWORD@127.0.0.1:23123/a\n(\"Bearer\" \"eyJhbGciOiJIUzUxMiJ9.eyJfdGsiOjEsImV4cCI6MTY4MTMwNDA4NiwiaWF0IjoxNjgxMzA0MDI2LCJzdWIiOiJvd25lciIsInppZCI6IjIwMjEwNjI5MTYzMzAwIn0.kZd3prYc79dt9efDsrYVHtKrjWyOWvfByjeeUB3hf_vs43V3SNJqmb8k-zTHVNWOK0-5orVPrg2tIAqbXqmkhg\" 600)\n```\n\nIf you do not want to use Basic Authentication, you can also send user identification and password as HTML form data:\n```sh\n# curl -X POST -d 'username=IDENT&password=PASSWORD' http://127.0.0.1:23123/a\n(\"Bearer\" \"eyJhbGciOiJIUzUxMiJ9.eyJfdGsiOjEsImV4cCI6MTY4MTMwNDA4OCwiaWF0IjoxNjgxMzA0MDI4LCJzdWIiOiJvd25lciIsInppZCI6IjIwMjEwNjI5MTYzMzAwIn0.qIEyOMFXykCApWtBaqbSESwTL96stWl2LRICiRNAXUjcY-mwx_SSl9L5Fj2FvmrI1K1RBvWehjoq8KZUNjhJ9Q\" 600)\n```\n\nIn all cases, you will receive a list with three elements that will contain all [[relevant data|00001012921000]] to be used for further API calls.\n\n**Important:** obtaining a token is a time-intensive process.\nZettelstore will delay every request to obtain a token for a certain amount of time.\nPlease take into account that this request will take approximately 500 milliseconds, under certain circumstances more.\n\nHowever, if [[authentication is not enabled|00001010040100]] and you send an authentication request, no user identification/password checking is done and you receive an artificial token immediate, without any delay:\n\n```sh\n# curl -X POST -u IDENT:PASSWORD http://127.0.0.1:23123/a\n(\"Bearer\" \"freeaccess\" 316224000)\n```\n\nIn this case, it is even possible to omit the user identification/password.\n\n=== HTTP Status codes\nIn all cases of successful authentication, a list is returned, which contains the token as the second element.\nA successful authentication is signaled with the HTTP status code 200, as usual.\n\nOther status codes possibly send by the Zettelstore:\n; ''400''\n: Unable to process the request.\n  In most cases the form data was invalid.\n; ''401''\n: Authentication failed.\n  Either the user identification is invalid or you provided the wrong password.\n; ''403''\n: Authentication is not active."))