Creating and managing API tokens

In this scenario, we’ll show you how to issue an API token for programmatic access to Tengri and use it for authentication, as well as how to view, update and revoke tokens. Finally, we’ll look at administrator actions: limiting the validity period of tokens and issuing a token for another user.

API tokens are useful in situations where interactive password-based login is not suitable: in scripts, CI/CD jobs, BI tools and other integrations. A token is linked to a user and inherits all their roles and privileges.

A full description of the commands and parameters for API tokens can be found on the page Operations with API tokens.

Issuing a token

Let’s issue a token for the current user. We’ll give it a meaningful name, set its validity period to 30 days and add a comment explaining its purpose.

CREATE API TOKEN ci_pipeline
    MAX DURATION '30d'
    COMMENT 'Токен для сборочного конвейера';
+-------------+------------------------------------------------------+---------------------------+
| name        | token                                                | expires_at                |
+-------------+------------------------------------------------------+---------------------------+
| ci_pipeline | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoi... | 2026-07-20T09:00:00+00:00 |
+-------------+------------------------------------------------------+---------------------------+
The value from the token column is displayed only once and cannot be recovered. Save it immediately in a secure location (for example, in your CI/CD secrets). If the token is lost or compromised, revoke it and issue a new one.

You do not need to specify a name or expiry date. In that case, the system will generate a name automatically, and the default expiry date will be 365 days:

CREATE API TOKEN;

Using the token for authentication

The token obtained must be presented with every request to Tengri. The request will only be successful if it is made on behalf of the user who issued the token.

Access via HTTP

When making a request to the HTTP gateway, the token is passed in the Authorization header:

curl -H "Authorization: Bearer <token>" \
     https://<tengri-host>/api/...

Alternatively, the token can be passed in the auth_token cookie.

Access via the tngri library

In the tngri library ( Python), the token is passed in the ws_token field of the client configuration. The client authenticates the WebSocket connection under the token’s owner:

import tngri

config = tngri.config.Config(
    ws_addr='ws://<tengri-host>:3001',  # адрес WebSocket-шлюза Tengri
    ws_token='<token>',                 # значение токена, полученное из результата CREATE API TOKEN
)
client = tngri.Client(config)

# Запрос выполняется от имени владельца токена со всеми его правами
df = client.sql('SELECT 1 AS answer')
print(df)

The gateway address and token can be set as the environment variables TNGRI_SITE_WS_ADDR and TNGRI_ACCESS_TOKEN — in which case the client is instantiated from the environment without the token being explicitly passed in the code:

import tngri

client = tngri.Client.from_env()
df = client.sql('SELECT 1 AS answer')
print(df)
$ TNGRI_SITE_WS_ADDR=ws://tengri.example.com:3001 \
    TNGRI_ACCESS_TOKEN=<token>\
    python script.py
Store the token value as a secret: pass it via environment variables or a CI/CD secret store, rather than hard-coding it in the source code.

Viewing your tokens

A list of issued tokens can be obtained using the command:

SHOW API TOKENS;

For a detailed description of the command, see here.

Changing a comment

You can update a token’s comment without changing the token value itself or its expiry date:

ALTER API TOKEN ci_pipeline SET COMMENT 'Перенесен на новый раннер';

For a detailed description of the command, see here.

Revoking a token

To immediately invalidate a token, revoke it:

DROP API TOKEN ci_pipeline;

For a detailed description of the command, see here.

Revocation is the correct response to a compromised account or a planned token rotation. If you suspect an account has been compromised, you can revoke all of the user’s tokens at once:

DROP ALL API TOKENS FOR USER <user_name>;

For a detailed description of the command, see here.

Token administration

The following actions are available only to the administrator (a user with the ADMIN ON CATALOG privilege or the built-in user admin).

Limiting token validity

By default, a user can issue a token valid for up to 365 days. To limit the maximum validity of tokens, the administrator sets a policy at the user or role level.

  1. Let’s limit the validity period of tokens for the user analyst to one day:

    ALTER USER analyst SET API TOKEN MAX DURATION '24h';

  2. Or let’s limit the validity period for all holders of the service_accounts role to 30 days:

    ALTER ROLE service_accounts SET API TOKEN MAX DURATION '30d';

Once the policy is in place, any attempt to issue a token with a longer validity period will be rejected with an error. If a user has multiple applicable restrictions (personal and role-based), the least restrictive one (the longest validity period) applies.

For a detailed description of the command, see here.

Issuing and managing tokens for another user

An administrator can manage tokens for any user by adding the FOR USER parameter to commands.

  1. Let’s issue a token for the user analyst on their behalf:

    CREATE API TOKEN report_bot
    FOR USER analyst
    MAX DURATION '90d'
    COMMENT 'Сервисный токен для выгрузки отчетов';

  2. Let’s view the tokens for the user analyst:

    SHOW API TOKENS FOR USER analyst;

  3. If necessary, let’s revoke this user’s token:

    DROP API TOKEN report_bot FOR USER analyst;
Without the FOR USER parameter, all commands operate on the current user’s tokens. A standard user (not an administrator) cannot use the FOR USER parameter.

Managing tokens in the web interface

Tokens can be managed not only via the commands SQL, but also via the web interface Tengri: in the Settings > API Tokens tab. This page provides full control over the current user’s tokens:

  • creating a token by specifying a name, expiry date and comment;

  • displaying the value of a new token once after creation, with a copy button;

  • editing the comment;

  • revoking a token;

  • viewing active tokens (with the option to hide expired and revoked ones).

See also