Skip to content

[feat] add API token management functionality#4080

Open
Duansg wants to merge 10 commits intoapache:masterfrom
Duansg:feat-token-manager
Open

[feat] add API token management functionality#4080
Duansg wants to merge 10 commits intoapache:masterfrom
Duansg:feat-token-manager

Conversation

@Duansg
Copy link
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
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.

1 participant