Skip to content

[feat] add API token management functionality#4080

Merged
tomsun28 merged 11 commits into
apache:masterfrom
Duansg:feat-token-manager
Mar 21, 2026
Merged

[feat] add API token management functionality#4080
tomsun28 merged 11 commits into
apache:masterfrom
Duansg:feat-token-manager

Conversation

@Duansg
Copy link
Copy Markdown
Member

@Duansg Duansg commented Mar 20, 2026

What's changed?

Previously, there was no way to manage HertzBeat API tokens once they were generated, which led to the following issues:

  1. Once a Token is shared with a third party for alert integration or log ingestion, the access permissions for that Token cannot be revoked, which poses a security risk.
  2. The Token generation button is scattered across various integration pages (alert integration, log integration), giving the impression that it is a feature specific to each integration rather than a global setting, which can easily confuse users.
  3. There is a lack of visibility regarding Tokens; it is unclear how many Tokens are in use within the system, who created them, or whether they are still actively in use.

Modification Details

  1. Persistent Storage of API Tokens: Do not store plaintext; display masked versions; record the creator, creation time, expiration time, and last access time.

  2. API Token Revocation Validation Filter: Runs after Sureness authentication to check whether the authenticated Token has been revoked. (Existing Tokens are not affected; backward compatibility is maintained.)

  3. API Token Expiration Time: When generating the token, you can select an expiration time (7, 30, 90, 180, or 365 days, or never expire). The expiration time is written to the JWT exp claim and is natively validated by the Sureness framework.

  4. Permissions Configuration Update (sureness.yml): The /api/account/token endpoints remain admin-only, and the controller layer keeps the same restriction. Only administrators can generate, list, and revoke API tokens; administrators can revoke any token.

  5. Managed Token Identification: Newly generated API tokens carry a dedicated managed=true JWT claim. Only these managed tokens are subject to database-backed lifecycle checks; legacy tokens without this claim continue to work for backward compatibility.

  6. Runtime Account and Role Revalidation: For managed tokens, each authenticated request revalidates the token owner’s current account status and role set. If the account is disabled, removed, or no longer has the required roles, the token is rejected even if the JWT itself has not yet expired.

  7. Fail-Closed Revocation Checking: Revocation and account-state validation no longer fail open. If token status validation cannot be completed because of a runtime/storage error, the request is denied instead of being silently allowed. lastUsedTime updates remain best-effort and do not block requests.

  8. Managed Token Lifecycle Tracking: Managed tokens now support full lifecycle operations, including generation, listing, revocation, last-access updates, and expiration-based invalidation, while keeping legacy token behavior unchanged.

  9. Frontend and E2E Alignment: The frontend token management flow and E2E tests were updated to match the new semantics, including explicit “never expire” handling and end-to-end coverage for token generation, usage, listing, and revocation.

Checklist

  • I have read the Contributing Guide
  • I have written the necessary doc or comment.
  • I have added the necessary unit tests and all cases have passed.

Add or update API

  • I have added the necessary e2e tests and all cases have passed.

API Token Generation
save

API token expiration validation
check

@Duansg Duansg requested review from tomsun28 and zqr10159 March 20, 2026 15:47
Copy link
Copy Markdown
Member

@tomsun28 tomsun28 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

@tomsun28 tomsun28 merged commit 3e6a796 into apache:master Mar 21, 2026
3 checks passed
@Duansg Duansg deleted the feat-token-manager branch March 21, 2026 17:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants