Api Tokens Api Create Api Token
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.
Owner console user id
3
The new token: a name, its access (READ_ONLY by default) and its lifetime in days (90 by default, at most 365).
Show optional properties
{
"name": "string"
}
{
"name": "siem-readonly",
"access": "READ_ONLY",
"expiresInDays": 30
}
Name for the token, unique among the owner's non-revoked tokens, without control characters
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 onlyFULL: Full. Also allows the approved write routes, still limited by the owner's role
Lifetime of the token in days, from 1 to 365; 90 when omitted
201 Created successful response envelope. The token metadata and, this once, the token itself
{
"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>"
}
Public token id, 12 lowercase base32 characters. It identifies the token in the console and in audit records and is not a secret
Id of the local console user that owns the token
Name the administrator gave the token, unique among the owner's non-revoked tokens
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 onlyFULL: Full. Also allows the approved write routes, still limited by the owner's role
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 revokedEXPIRED: Expired. The expiry time has passed and the token is refusedREVOKED: Revoked. An administrator revoked the token and it is refused
Time at which an administrator issued the token
Username of the administrator who created the token
When the token stops being accepted
When the token was last used; absent for a new token
When the token was revoked; absent for a new token
The full bearer token, sent as Authorization Bearer. It is returned only by this response and cannot be retrieved again
Response Headers
Always no-store, so no cache keeps the secret
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
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
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 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
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 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)
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
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 Not Found error response (USER_NOT_FOUND, or API_TOKENS_DISABLED while the feature flag is off)
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
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 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
"ApiErrorResponse Object"
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"name":"string"}' https://{api_host}/api/v1/users/{userId}/api-tokens