Api Tokens Api Create Api Token

Api Tokens Api Create Api Token
Create an API token and return its secret once (Administrator only)

The owner must be an active LOCAL user (the protected default administrator is eligible), and may hold at most 10 non-revoked, unexpired tokens. The response carries Cache-Control no-store and is the only time the token is returned. Audited as API_TOKEN_CREATE without the secret. Bearer tokens cannot call this route.

Request
URI
POST
https://{api_host}/api/v1/users/{userId}/api-tokens
COPY
Path Parameters
integer
userId
Required  

Owner console user id

userId example
3

Request Body

The new token: a name, its access (READ_ONLY by default) and its lifetime in days (90 by default, at most 365).

CreateApiTokenRequest of type(s) application/json
Required  

Show optional properties

{
    "name": "string"
}
{
    "name": "siem-readonly",
    "access": "READ_ONLY",
    "expiresInDays": 30
}
string
name
Required  
Constraints: minLength: 1 maxLength: 64

Name for the token, unique among the owner's non-revoked tokens, without control characters

string
access
Optional

What an API token may do, on top of its owner's role and the approved bearer routes

  • READ_ONLY: Read-only. Allows GET and HEAD on the approved read routes only
  • FULL: Full. Also allows the approved write routes, still limited by the owner's role
Enumeration: READ_ONLY, FULL
integer As int32 As int32
expiresInDays
Optional
Constraints: minimum: 1 maximum: 365 default: 90

Lifetime of the token in days, from 1 to 365; 90 when omitted

Authentication
This operation uses the following authentication methods.
Responses
201

201 Created successful response envelope. The token metadata and, this once, the token itself

Returns CreatedApiTokenDto of type(s) application/json
{
    "tokenId": "k3x7q2m9z4tb",
    "ownerUserId": 3,
    "name": "siem-readonly",
    "access": "READ_ONLY",
    "status": "ACTIVE",
    "createdAt": "2026-01-15T09:30:00Z",
    "createdBy": "alice",
    "expiresAt": "2026-02-14T09:30:00Z",
    "lastUsedAt": null,
    "revokedAt": null,
    "token": "<redacted>"
}
string
tokenId
Required  

Public token id, 12 lowercase base32 characters. It identifies the token in the console and in audit records and is not a secret

integer As int64 As int64
ownerUserId
Required  

Id of the local console user that owns the token

string
name
Required  
Constraints: minLength: 1 maxLength: 64

Name the administrator gave the token, unique among the owner's non-revoked tokens

string
access
Required  

What an API token may do, on top of its owner's role and the approved bearer routes

  • READ_ONLY: Read-only. Allows GET and HEAD on the approved read routes only
  • FULL: Full. Also allows the approved write routes, still limited by the owner's role
Enumeration: READ_ONLY, FULL
string
status
Required  

Where an API token is in its life, derived from its revocation and expiry times

  • ACTIVE: Active. The token is accepted until it expires or is revoked
  • EXPIRED: Expired. The expiry time has passed and the token is refused
  • REVOKED: Revoked. An administrator revoked the token and it is refused
Enumeration: ACTIVE, EXPIRED, REVOKED
string As date-time As date-time
createdAt
Required  

Time at which an administrator issued the token

string
createdBy
Required  

Username of the administrator who created the token

string As date-time As date-time
expiresAt
Required  

When the token stops being accepted

string As date-time As date-time
lastUsedAt
Required  

When the token was last used; absent for a new token

string As date-time As date-time
revokedAt
Required  

When the token was revoked; absent for a new token

string
token
Required  

The full bearer token, sent as Authorization Bearer. It is returned only by this response and cannot be retrieved again

Response Headers

string
Cache-Control

Always no-store, so no cache keeps the secret


400

400 Bad Request: API_TOKEN_NAME_INVALID when the name is empty, longer than 64 characters or has control characters; API_TOKEN_EXPIRY_INVALID when expiresInDays is outside 1 to 365; INVALID_ARGUMENT when the userId path variable is not a number; MALFORMED_REQUEST when the body cannot be read

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


401

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


403

403 Forbidden: FORBIDDEN when the signed-in role is not allowed to call this operation; CSRF_ERROR when the X-XSRF-TOKEN header is missing or wrong on a POST, PUT, PATCH or DELETE (only POST /api/v1/auth/login is exempt, and a request without a valid session gets 401 UNAUTHENTICATED instead); PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt); LICENSE_REQUIRED or LICENSE_EXPIRED while the license pool is restricted (no license, or expired past grace) (exempt: every route under /api/v1/auth, GET /api/v1/user/preferences, GET /api/v1/licensing/summary and POST /api/v1/licensing/licenses)

Returns ForbiddenWrite of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


404

404 Not Found error response (USER_NOT_FOUND, or API_TOKENS_DISABLED while the feature flag is off)

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


409

409 Conflict: API_TOKEN_NAME_EXISTS when the owner has a non-revoked token with that name; API_TOKEN_LIMIT_REACHED at 10 active tokens; API_TOKEN_OWNER_NOT_ELIGIBLE for an SSO or inactive user

Returns ApiErrorResponse of type(s) application/json
"ApiErrorResponse Object"
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"name":"string"}' https://{api_host}/api/v1/users/{userId}/api-tokens