title: API: Renew an access token
role: manual
tags: #api #manual #zettelstore
syntax: zmk
back: 00001010040700 00001012000000
backward: 00001010040700 00001012000000 00001012920000 00001012921000
box-number: 1
copyright: (c) 2020-present by Detlef Stern <ds@zettelstore.de>
created: 20210126175322
forward: 00001010040100 00001012050200 00001012920000 00001012921000
lang: en
license: EUPL-1.2-or-later
modified: 20230412160219
published: 20230412160219
visibility: public

An access token is only valid for a certain duration.
Since the [[authentication process|00001012050200]] will need some processing time, there is a way to renew the token without providing full authentication data.

Send a HTTP PUT request to the [[endpoint|00001012920000]] ''/a'' and include the current access token in the ''Authorization'' header:
```{="sh"}
# curl -X PUT -H 'Authorization: Bearer TOKEN' http://127.0.0.1:23123/a
("Bearer" "eyJhbGciOiJIUzUxMiJ9.eyJfdGsiOjEsImV4cCI6MTY4MTMwNDA4NiwiaWF0IjoxNjgxMzA0MDI2LCJzdWIiOiJvd25lciIsInppZCI6IjIwMjEwNjI5MTYzMzAwIn0.kZd3prYc79dt9efDsrYVHtKrjWyOWvfByjeeUB3hf_vs43V3SNJqmb8k-zTHVNWOK0-5orVPrg2tIAqbXqmkhg" 456)
```
You may receive a new access token, or the current one if it was obtained not a long time ago.
However, the lifetime of the returned [[access token|00001012921000]] is accurate.

If [[authentication is not enabled|00001010040100]] and you send a renew request, no checking is done and you receive an artificial token immediate, without any delay:
```{="sh"}
# curl -X PUT -H 'Authorization: Bearer freeaccess' http://127.0.0.1:23123/a
("Bearer" "freeaccess" 316224000)
```
In this case, it is even possible to omit the access token.
=== HTTP Status codes
; ''200''
: Renew process was successful, the body contains a [[list|00001012921000]] with the relevant data.
; ''400''
: The renew process was not successful.
There are several reasons for this.
Maybe access bearer token was not valid.

  Probably you should [[authenticate|00001012050200]] again with user identification and password.