API: Authenticate a client

00001012050200 · Info · (manual) · #api #manual #zettelstore (all)

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.