|
API tokens are especially convenient for machine access to non-public endpoints of the REST API that are indicated with a padlock icon in the [[https://stats.adam.nic.cz/swagger][Swagger UI]].
|
|
Autentication with API tokens (also known as /bearer authentication/) is a popular alternative to sending a username and password with an HTTP request. In our case, it is especially convenient for machine access to protected endpoints of the REST API, indicated with a padlock icon in the [[https://stats.adam.nic.cz/swagger][Swagger UI]].
|
|
|
|
|
|
|
|
An API token is a cryptic string of 36 characters (hexadecimal digits and dashes). Sending it inside the ~Authorization~ HTTP header allows for accessing protected resources that the token was created for.
|
|
|
|
|
|
|
|
With the popular [[https://curl.se][curl]] tool it can be used as follows:
|
|
|
|
|
|
#+begin_src sh :results output
|
|
#+begin_src sh :results output
|
|
curl -s -H 'Authorization: Bearer e405fa87-e346-4b30-a986-aa7b04a4cc77' \
|
|
curl -H 'Authorization: Bearer a67fb655-60f2-4d00-b79e-bea203086bc3' \
|
|
'https://stats.adam.nic.cz/cz_dns_server_locations'
|
|
'https://stats.adam.nic.cz/ca_qps_total'
|
|
#+end_src
|
|
#+end_src
|
|
|
|
|
|
|
|
* API token management
|
|
|
|
|
|
|
|
Each user with granted access to some protected resources can create, inspect and revoke API tokens after logging in and selecting *Manage tokens* in the user menu.
|
|
|
|
|
|
|
|
In order to create a new API token, the following info has to be specified in the creation form:
|
|
|
|
|
|
|
|
- token name :: An arbitrary string that will serve for easy identification of the token
|
|
|
|
- resources :: Selection of API paths that the token may be used for. By default, all paths accessible to the user are selected.
|
|
|
|
- expiration :: The date (and optionally time) after which the token can no longer be used. By default, a token doesn't expire.
|
|
|
|
|
|
|
|
For example, assume that an authenticated user wants to create an API token named /example-token/ so that
|
|
|
|
- it can grant access only to a single API endpoint, ~/ca_qps_total_1h~
|
|
|
|
- it expires on 23 April 2021
|
|
|
|
The creation form then should be modified as shown in this screenshot:
|
|
|
|
|
|
|
|
[[figures/token.create.png]]
|
|
|
|
|
|
|
|
All paths (both public and protected) accessible to the user can be viewed after expanding the item at the bottom of the form.
|
|
|
|
|
|
|
|
After clicking the *Create a new token* button, the shiny now token should be displayed in the table at the top:
|
|
|
|
|
|
|
|
[[figures/token-table.png]]
|
|
|
|
|
|
|
|
The token can be revoked before the expiration time by clicking the *Revoke* button. |