API: Authenticate a client
manual
api manual zettelstore
zmk
00001012000000 00001012050400 00001012050600 00001012051200 00001012051400 00001012053300 00001012053400 00001012053500 00001012053600 00001012080200
00001010040700 00001012000000 00001012050400 00001012050600 00001012051200 00001012051400 00001012053300 00001012053400 00001012053500 00001012053600 00001012080200 00001012920000 00001012921000
1
(c) 2020-present by Detlef Stern <ds@zettelstore.de>
20210126175322
00001004010000 00001010040100 00001010040200 00001010040700 00001012920000 00001012921000
en
EUPL-1.2-or-later
20230412150544
20230412150544
public
Authentication for future API calls is done by sending a user identification and a password to the Zettelstore to obtain an 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 token-lifetime-api of the startup configuration (typically 10 minutes).
The simplest way is to send user identification (IDENT) and password (PASSWORD) via HTTP Basic Authentication and send them to the endpoint /a with a POST request:
# curl -X POST -u IDENT:PASSWORD http://127.0.0.1:23123/a
("Bearer" "eyJhbGciOiJIUzUxMiJ9.eyJfdGsiOjEsImV4cCI6MTY4MTMwNDA2MiwiaWF0IjoxNjgxMzA0MDAyLCJzdWIiOiJvd25lciIsInppZCI6IjIwMjEwNjI5MTYzMzAwIn0.kdF8PdiL50gIPkRD3ovgR6nUXR0-80EKAXcY2zVYgYvryF09iXnNR3zrvYnGzdrArMcnvAYqVvuXtqhQj2jG9g" 600)
Some tools, like curl, also allow to specify user identification and password as part of the URL:
# curl -X POST http://IDENT:PASSWORD@127.0.0.1:23123/a
("Bearer" "eyJhbGciOiJIUzUxMiJ9.eyJfdGsiOjEsImV4cCI6MTY4MTMwNDA4NiwiaWF0IjoxNjgxMzA0MDI2LCJzdWIiOiJvd25lciIsInppZCI6IjIwMjEwNjI5MTYzMzAwIn0.kZd3prYc79dt9efDsrYVHtKrjWyOWvfByjeeUB3hf_vs43V3SNJqmb8k-zTHVNWOK0-5orVPrg2tIAqbXqmkhg" 600)
If you do not want to use Basic Authentication, you can also send user identification and password as HTML form data:
# curl -X POST -d 'username=IDENT&password=PASSWORD' http://127.0.0.1:23123/a
("Bearer" "eyJhbGciOiJIUzUxMiJ9.eyJfdGsiOjEsImV4cCI6MTY4MTMwNDA4OCwiaWF0IjoxNjgxMzA0MDI4LCJzdWIiOiJvd25lciIsInppZCI6IjIwMjEwNjI5MTYzMzAwIn0.qIEyOMFXykCApWtBaqbSESwTL96stWl2LRICiRNAXUjcY-mwx_SSl9L5Fj2FvmrI1K1RBvWehjoq8KZUNjhJ9Q" 600)
In all cases, you will receive a list with three elements that will contain all relevant data to be used for further API calls.
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.
However, if 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:
# curl -X POST -u IDENT:PASSWORD http://127.0.0.1:23123/a
("Bearer" "freeaccess" 316224000)
In this case, it is even possible to omit the user identification/password.
HTTP Status codes
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.
Other status codes possibly send by the Zettelstore:
400
Unable to process the request. In most cases the form data was invalid.
401
Authentication failed. Either the user identification is invalid or you provided the wrong password.
403
Authentication is not active.