---
title: "Issue user authentication token"
method: POST
path: "/v1/users/{user-id}/tokens"
tags: ["Users"]
---

# Issue user authentication token

`POST /v1/users/{user-id}/tokens`

Issue a new authentication token for the user. The clear-text token value is
returned in this response only - the server drops it as soon as the response is
built, so it cannot be read back from a listing and a lost token has to be revoked
and re-issued. A user may issue tokens for themselves; issuing tokens for another
user requires MANAGE_USERS access right.

## Path parameters

- `user-id` integer, required

## Request body

- AuthenticationTokenCreateInput — Request body for issuing a new authentication token.
  - `validFor` integer, required — Validity period in seconds from now. For a persistent token the resulting expiration time is additionally required to be not later than 2038-01-19T03:14:07Z, because it is stored in a 32-bit database column; a longer period is rejected with 400. A non-persistent token (ephemeral, service or single-use) is additionally bound by the absolute lifetime cap "WebAPI.AuthTokenMaxLifetime" (24 hours by default). A longer validity period is accepted but silently reduced to the cap, so the returned expirationTime can be earlier than the requested one.
  - `persistent` boolean — True to issue a persistent (database-backed) token, false for an ephemeral one.
  - `singleUse` boolean — True to issue a single-use token, which is destroyed by the login that spends it and therefore authenticates exactly one session. Intended for handing a session over to another process (for example a launcher spawning the management console). A single-use token can only be spent on an NXCP login; presenting it as a REST bearer credential is rejected with 401 and does not consume it. Single-use tokens are kept in memory only and do not survive a server restart, so this option requires "persistent" to be false. Because "persistent" defaults to true, a request body containing only "singleUse": true is rejected with 400 - "persistent": false must be sent explicitly.
  - `description` string — Optional human-readable token description, limited to 127 characters; a longer value is rejected with 400. The limit is the width of the database column a persistent token is stored in, and is applied to all token types.

## Response `201`

Token issued successfully

- AuthenticationToken — An authentication token issued for a user.
  - `id` integer — Token ID. Assigned only to persistent tokens; ephemeral, service and single-use tokens are always reported with 0 and therefore cannot be revoked by ID.
  - `userId` integer — ID of the user the token was issued for.
  - `persistent` boolean — True if the token is persisted in the database (long-lived API token).
  - `service` boolean — True if this is a service token.
  - `singleUse` boolean — True if the token is single-use. Such a token is destroyed by the login that spends it, so it authenticates exactly one session. It can only be spent on an NXCP login (management console or other NXCP client) and is rejected with 401 if presented as a REST bearer credential.
  - `description` string — Human-readable token description.
  - `issuingTime` integer — Token issuing time (UNIX timestamp, seconds).
  - `expirationTime` integer — Token expiration time (UNIX timestamp, seconds).
  - `value` string — Clear-text token value. Returned only by the create operation, which is the single point where the server gives it out; it is absent from token listings. A lost token cannot be recovered and has to be revoked and re-issued.

## Other responses

- `400` — Invalid user ID, missing/invalid validFor, singleUse requested together with persistent (single-use tokens are memory-only and require "persistent": false), a description longer than 127 characters, or a persistent token with an expiration time beyond 2038-01-19T03:14:07Z (neither fits the database columns)
- `401` — Unauthorized
- `403` — Access denied (not self and no MANAGE_USERS right)
- `404` — User not found

---

[API](https://skmtc.net/netxms/apis/netxms-api.md) · [All operations](https://skmtc.net/netxms/apis/netxms-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/netxms/netxms-api/versions/14d93e5115dd/schema)