title: API: Authenticate a client
role: manual
tags: #api #manual #zettelstore
syntax: zmk
back: 00001012000000 00001012050400 00001012050600 00001012051200 00001012051400 00001012053300 00001012053400 00001012053500 00001012053600 00001012053800 00001012080200
backward: 00001010040700 00001012000000 00001012050400 00001012050600 00001012051200 00001012051400 00001012053300 00001012053400 00001012053500 00001012053600 00001012053800 00001012080200 00001012920000 00001012921000
box-number: 1
copyright: (c) 2020-present by Detlef Stern <ds@zettelstore.de>
created: 20210126175322
forward: 00001010040100 00001010040200 00001010040700 00001012920000 00001012921000
lang: en
license: EUPL-1.2-or-later
modified: 20251218191625
published: 20251218191625
visibility: public

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).
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](00001004010000#token-lifetime-api) (typically 10 minutes).

The simplest way is to send user identification (`IDENT`) and password (`PASSWORD`) via [HTTP Basic Authentication](https://datatracker.ietf.org/doc/html/rfc7617) and send them to the [endpoint](00001012920000) `/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](https://curl.se/), also allow you 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 containing three elements with all [relevant data](00001012921000) needed 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](00001010040100) and you send an authentication request, no user identification/password checking is done and you receive an artificial token immediately, 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 sent by the Zettelstore: