title: API: Check for authentication
role: manual
tags: #api #manual #zettelstore
syntax: zmk
back: 00001012000000 00001012080100
backward: 00001012000000 00001012080100
box-number: 1
copyright: (c) 2020-present by Detlef Stern <ds@zettelstore.de>
created: 20220103224858
forward: 00001010040100 00001012050200 00001012920000
lang: en
license: EUPL-1.2-or-later
modified: 20220908163156
published: 20220908163156
visibility: public

API clients typically wants to know, whether [[authentication is enabled|00001010040100]] 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|00001012050200]].
If authentication is disabled, these steps are not needed.

To check for enabled authentication, you must send a HTTP POST request to the [[endpoint|00001012920000]] ''/x'' and you must specify the query parameter ''cmd=authenticated''.
```{="sh"}
# 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.