API: Check for authentication

00001012080200 · Info · (zettel) · #api #manual #zettelstore

API clients typically wants to know, whether authentication is enabled or not. If authentication is enabled, they present some form of user interface to get user name and password for the actual authentication. Then they try to obtain an access token. If authentication is disabled, these steps are not needed.

To check for enabled authentication, you must send a HTTP POST request to the endpoint /x and you must specify the query parameter _cmd=authenticated.

# curl -X POST 'http://127.0.0.1:23123/x?_cmd=authenticated'

If authentication is not enabled, you will get a HTTP status code 200 (OK) with an empty HTTP body.

Otherwise, authentication is enabled. If you provide a valid access token, you will receive a HTTP status code 204 (No Content) with an empty HTTP body. If you did not provide a valid access token (with is the typical case), you will get a HTTP status code 401 (Unauthorized), again with an empty HTTP body.

HTTP Status codes

200
Authentication is disabled.
204
Authentication is enabled and a valid access token was provided.
400
Request was not valid. There are several reasons for this. Most likely, no query parameter _cmd was given, or it did not contain the value authenticate.
401
Authentication is enabled and not valid access token was provided.