API Tokens

This API endpoint lets you create, list, update, revoke and delete the API tokens of your organization, so you can manage token lifecycle programmatically (for example, rotating tokens on a schedule).

Info

Only admins can manage tokens. Requests from non-admin accounts return 403 - Forbidden.

Create token

Creates an API token owned by the calling account.

Warning

The token value is returned once, in this response only. Store it securely right away - it can't be retrieved again.

HTTP request

POST  https://public-api.linearb.io/api/v1/tokens

Body parameters

Parameter name	Value	Description
name (required)	string	Display name of the token. (Max length: 100)
expires_at	string (date, `YYYY-MM-DD`)	The day the token stops working (UTC). Must be after today and at most 2 years ahead. Omit for no expiry.

Example

{
  "name": "ci-pipeline",
  "expires_at": "2027-01-31"
}

Responses

201 - Successful Response

{
  "id": 0,
  "name": "string",
  "token": "string",
  "prefix": "string",
  "source": "string",
  "expires_at": "2026-10-11T08:26:52.440Z",
  "created_at": "2026-10-11T08:26:52.440Z"
}

400 - Bad Request

401 - Unauthorized

403 - Forbidden (only admins can manage tokens)

404 - Not Found

405 - Method Not Allowed

409 - Conflict

422 - Validation Error

500 - Internal Server Error

504 - Gateway Timeout

List tokens

Lists the organization API tokens. By default, tokens created in the UI and through the API are returned.

HTTP request

GET  https://public-api.linearb.io/api/v1/tokens

Query parameter

Parameter name	Value	Description
status	string	Only tokens in this status. Valid values are: "active" "revoked" "expired"
source	string	Only tokens created this way. Valid values are: "user" "api" "otel" (Default: "user" and "api")
limit	integer	The maximum number of tokens to return. (Minimum: 1)
offset	integer	Number of tokens to skip. (Minimum: 0)

Responses

200 - Successful Response

{
  "total": 0,
  "items": [
    {
      "id": 0,
      "name": "string",
      "prefix": "string",
      "owner_email": "string",
      "role": "string",
      "status": "string",
      "source": "string",
      "expires_at": "2026-10-11T08:26:52.443Z",
      "created_at": "2026-10-11T08:26:52.443Z",
      "last_used_at": "2026-10-11T08:26:52.443Z"
    }
  ]
}

The prefix is the first characters of the token, to help you recognize it - it is not a secret.

400 - Bad Request

401 - Unauthorized

403 - Forbidden (only admins can manage tokens)

404 - Not Found

405 - Method Not Allowed

409 - Conflict

422 - Validation Error

500 - Internal Server Error

504 - Gateway Timeout

Update token

Renames a token, revokes it, or changes its expiry. A token that a detection setting uses cannot be revoked until that setting changes.

HTTP request

PATCH  https://public-api.linearb.io/api/v1/tokens/{token_id}

Path parameters

Parameter name	Value	Description
token_id (required)	integer	Token ID. (Minimum: 1)

Body parameters

Parameter name	Value	Description
name	string	New display name. (Max length: 100)
status	string	Set to "revoked" to revoke the token.
expires_at	string (date, `YYYY-MM-DD`)	The day the token stops working (UTC). Must be after today and at most 2 years ahead. `null` means the token never expires. Omit to keep the current expiry.

Examples

Revoke a token

{
  "status": "revoked"
}

Change a token's expiry

{
  "expires_at": "2027-06-30"
}

Responses

200 - Successful Response

{
  "id": 0,
  "name": "string",
  "prefix": "string",
  "owner_email": "string",
  "role": "string",
  "status": "string",
  "source": "string",
  "expires_at": "2026-10-11T08:26:52.445Z",
  "created_at": "2026-10-11T08:26:52.445Z",
  "last_used_at": "2026-10-11T08:26:52.445Z"
}

400 - Bad Request

401 - Unauthorized

403 - Forbidden (only admins can manage tokens)

404 - Not Found (token not found)

405 - Method Not Allowed

409 - Conflict (a detection setting uses the token, the token is an otel token, or - for an expiry change - the token is revoked or expired)

422 - Validation Error

500 - Internal Server Error

504 - Gateway Timeout

Delete token

Permanently deletes a token. Revoke an active token first. A token that a detection setting uses cannot be deleted until that setting changes.

HTTP request

DELETE  https://public-api.linearb.io/api/v1/tokens/{token_id}

Path parameters

Parameter name	Value	Description
token_id (required)	integer	Token ID. (Minimum: 1)

Responses

200 - Successful Response

204 - Successful Response

400 - Bad Request

401 - Unauthorized

403 - Forbidden (only admins can manage tokens)

404 - Not Found (token not found)

405 - Method Not Allowed

409 - Conflict (the token is active, a detection setting uses it, or the token is an otel token)

422 - Validation Error

500 - Internal Server Error

504 - Gateway Timeout