Operations with API tokens

An API token is a long-lived, revocable access token that a user can generate themselves using the SQL commands. The token is presented for authentication when making requests to Tengri via HTTP and WebSocket (for example, from scripts, CI/CD, BI tools and other software clients).

Unlike a password, an API token:

  • is issued and revoked via separate commands and does not require a password to be entered with every request;

  • is linked to a specific user and inherits their roles and privileges;

  • has a limited validity period and can be revoked at any time;

  • is stored in the system only as a hash — the token itself cannot be recovered once issued.

The token value is displayed exactly once — in the output of the CREATE API TOKEN command. Save it immediately: it is impossible to recover the token later. If lost, simply revoke the old token and issue a new one.

Token management commands

By default, a user can manage only their own tokens. Managing another user’s tokens (via the FOR USER parameter) is available only to the administrator. For more details, see Authorization model.

Create token

CREATE API TOKEN [<name>]
    [FOR USER <user_name>]
    [MAX DURATION '<duration>']
    [COMMENT '<text>'];

Issues a new API token and returns its value. All parameters are optional.

The command returns a single string with three columns:

+----------+----------------------------------------------+---------------------------+
| name     | token                                        | expires_at                |
+----------+----------------------------------------------+---------------------------+
| ...      | ...                                          | ...                       |
+----------+----------------------------------------------+---------------------------+

  • name — the name of the issued token;

  • token — the token value (displayed only once);

  • expires_at — the expiry time in UTC.

The value in the token column is confidential information equivalent to a password. If the value is compromised, revoke the token immediately using the command DROP API TOKEN.

The <name> parameter

An optional token name. The name must be unique amongst tokens for a single user. If no name is specified, the system generates it automatically in the format <user>_<uuid>.

The FOR USER parameter

The optional parameter FOR USER <user_name> issues a token on behalf of another user. Available only to the administrator (see Authorization model). If the parameter is omitted, the token is issued for the current user.

The MAX DURATION parameter

The optional MAX DURATION '<duration>' parameter specifies the requested token validity period. If this parameter is not specified, the default validity period is 365 days.

The requested validity period cannot exceed the maximum period set for the user or their roles by the policy SET API TOKEN MAX DURATION:

  • if the requested duration exceeds the set threshold, the command will fail;

  • if the MAX DURATION parameter is omitted, the token will be issued with the minimum validity period permitted by all of the user’s restrictions.

The value <duration> is a duration string consisting of segments of the form number+unit. Supported units:

  • s — seconds

  • m — minutes

  • h — hours

  • d — days

Segments can be combined, for example: '30d', '24h', '1h30m', '2h45m30s'.

The COMMENT parameter

The optional COMMENT '<text>' parameter adds an arbitrary text description to the token (for example, the token’s purpose or the name of the service using it). The comment can be changed later using the command ALTER API TOKEN.

See examples

  • Issuing a token for yourself with the default name and expiry time, and an empty comment:

    CREATE API TOKEN;

  • Issuing a named token with a 30-day expiry and a comment:

    CREATE API TOKEN ci_pipeline
    MAX DURATION '30d'
    COMMENT 'Основная сборка';

  • Issuing a token for another user (administrators only):

    CREATE API TOKEN report_bot
    FOR USER analyst
    MAX DURATION '90d';

Alter token

ALTER API TOKEN '<name>' [FOR USER <user_name>] SET COMMENT '<text>';

Changes the comment on an existing token.

The token value and its validity period remain unchanged.

The parameter FOR USER <user_name> changes another user’s token and is available only to the administrator (see Authorization model).

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

Drop token

DROP API TOKEN '<name>' [FOR USER <user_name>];

Revokes the specified token.

Once revoked, the token immediately ceases to be valid across all authentication paths — reactivation is not possible.

The FOR USER <user_name> parameter revokes another user’s token and is available only to the administrator (see Authorization model).

In the event of compromise, loss or the need to replace a token, it is recommended to revoke the token immediately using this command.
See example 
DROP API TOKEN ci_pipeline;

Drop all tokens for user

DROP ALL API TOKENS [FOR USER <user_name>];

Revokes all of a user’s active tokens with a single command.

Useful if you suspect an account has been compromised.

The FOR USER <user_name> parameter revokes another user’s tokens and is only available to the administrator (see Authorization model).

This command revokes all of a user’s active tokens at once. All clients using these tokens (scripts, CI/CD, integrations) will lose access to the system and will require new tokens to be issued.

Output a list of all tokens

SHOW API TOKENS [FOR USER <user_name>];

Displays a list of a user’s tokens.

The token values are not displayed — they cannot be viewed once issued. The list includes active, revoked and expired tokens.

The FOR USER <user_name> parameter displays another user’s tokens and is only available to the administrator (see Authorization model). If the administrator does not specify this parameter, only tokens issued by himself are displayed.

Output format:

+------+--------------+------------+------------+------------+---------+
| name | last_used_at | created_at | expires_at | revoked_at | comment |
+------+--------------+------------+------------+------------+---------+
| ...  | ...          | ...        | ...        | ...        | ...     |
+------+--------------+------------+------------+------------+---------+

  • name — token name;

  • last_used_at — time the token was last used (empty if the token has never been used);

  • created_at — time of issue;

  • expires_at — expiry time;

  • revoked_at — revocation time (empty for valid tokens);

  • comment — comment on the token.

All timestamps are returned in UTC.

The last_used_at timestamp is updated no more than once every 5 minutes, so the most recent uses may be displayed with a slight delay.

Commands for managing token policies

Alter token max duration

ALTER USER <user_name> SET API TOKEN MAX DURATION '<duration>';

ALTER ROLE <role_name> SET API TOKEN MAX DURATION '<duration>';

Sets the maximum validity period for tokens issued by a user or role.

  • The format <duration> matches the format of the MAX DURATION of the CREATE API TOKEN command.

  • When issuing a token, the least restrictive (longest) threshold is applied from among those set for the user themselves and all their active roles.

  • A request for a token with a validity period exceeding the threshold is rejected. If a threshold is set, the default validity period is also limited by it.

This policy can only be set by a user with administrative rights (see Authorization model).

See examples

  • Limit the validity period of tokens for the analyst user to one day:

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

  • Limit the validity period of tokens for the service_accounts role to 30 days:

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

Authorization model

Token management is divided into two access levels.

Action Who can perform

Managing their own tokens (without FOR USER)

Any user — no additional privileges required.

Managing another user’s tokens (with FOR USER)

Administrator only.

Setting the SET API TOKEN MAX DURATION policy

Administrator only.

An administrator is defined as a user with the ADMIN ON CATALOG privilege, as well as the built-in user admin.

Managing your own tokens does not require any specific privileges: every user can issue, view and revoke their own tokens.

Using a token for authentication

An issued token must be presented with every request to the HTTP and WebSocket gateways at Tengri in one of two ways:

  • in the HTTP request header Authorization: Bearer <token>;

  • in a cookie auth_token=<token>.

The token authenticates the client as its owner, so all of that user’s roles and privileges apply.

See example

  • Making a request to the REST gateway with a token in the Authorization header:

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

Security features

  • Stored as a hash only. Only the token’s hash is stored in the database — the actual value is not saved. A database breach does not reveal any values that can be used for authentication.

  • Immediate revocation. During each authentication, not only is the token’s signature verified, but also its validity in the store; therefore, the DROP API TOKEN command takes effect immediately, rather than ‘upon expiry’.

  • Dedicated signing key. Tokens are signed using a separate key derived from the deployment master key; rotation of the master key automatically rotates the token signing key as well.

  • Validity period restriction. The SET API TOKEN MAX DURATION policy limits the maximum lifetime of tokens at user or role level.

See also