Sign in

v

latestOpenAPI 3.0.2raw.githubusercontent.com2026-08-08261120478.8 KB
Users

Issue user authentication token

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.

post/v1/users/{user-id}/tokens

Path parameters

user-idinteger required

User ID

Request body

validForinteger 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.

persistentboolean

True to issue a persistent (database-backed) token, false for an ephemeral one.

singleUseboolean

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.

descriptionstring

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

Token issued successfully

idinteger

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.

userIdinteger

ID of the user the token was issued for.

persistentboolean

True if the token is persisted in the database (long-lived API token).

serviceboolean

True if this is a service token.

singleUseboolean

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.

descriptionstring

Human-readable token description.

issuingTimeinteger

Token issuing time (UNIX timestamp, seconds).

expirationTimeinteger

Token expiration time (UNIX timestamp, seconds).

valuestring

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.