Provided warnings to admins when API keys are going to expire

[swicken-dotcms]

Parent Issue

No response

User Story

As a user I want to be alerted when API keys associated with users in dotCMS are going to expire so I can update them and avoid downtime

Acceptance Criteria

1. Administrators and the user that the API key is on should receive notifications when an API key is going to expire.

Proposed Objective

Technical User Experience

Proposed Priority

Priority 2 - Important

External Links... Slack Conversations, Support Tickets, Figma Designs, etc.

Related ticket: https://dotcms.zendesk.com/agent/tickets/112615

Assumptions & Initiation Needs

No response

Quality Assurance Notes & Workarounds

No response

Sub-Tasks & Estimates

No response

[github-actions[bot]]

This issue is stale because it has been open 90 days with no activity. Remove stale label or comment or this will be closed in 30 days.

[github-actions[bot]]

PRs:

• https://github.com/dotCMS/core/pull/32419

[erickgonzalez]

🔧 Technical Handover: Token Expiration Alert Feature

Objective

Develop a feature to identify and notify users of API tokens that are about to expire. This includes a configurable backend API, role-based access control, and optional user-facing alerts.

⸻

🧩 Functional Requirements

1. Token Expiry Check Method • Implement a backend method that retrieves API tokens set to expire within X days. • X is configurable via a variable (e.g., EXPIRING_TOKEN_LOOKAHEAD_DAYS). Default: 7 days. • The method returns a list of APIToken objects filtered by user role (see below).

⸻

🛂 Role-Based Behavior • Admin Users: Receive all tokens that are expiring within the next X days. • Limited Users: Receive only their own tokens that are expiring in the next X days.

⸻

🌐 REST API Endpoint • Endpoint: GET /v1/apitoken/expiring • Returns: JSON array of APIToken objects (based on user role). • Authentication Required: Yes ⸻

💬 Alert Messages • Limited User: “You have API Tokens that are about to expire. Please let your Administrator know about this.” • Admin User: “Some API Tokens are about to expire. Please review them here [link to REST API, open in new tab].” • Messages should: • Be shown only if expiring tokens are found. • Respect the DISPLAY_EXPIRING_TOKEN_ALERTS config flag (default: true). • Be shown based on the user’s role.

⸻

⚙️ Configuration Parameters

• EXPIRING_TOKEN_LOOKAHEAD_DAYS = Days in advance to check for expiration. Default: 7
• DISPLAY_EXPIRING_TOKEN_ALERTS = Enable/disable the expiration messages. Default: true

⸻

✅ Tests

📦 Token Expiry Method • Returns tokens expiring within the default number of days (7) • Returns tokens expiring within a custom number of days (e.g., 3, 10) • Handles empty result when no tokens are expiring • Handles invalid configuration (e.g., negative or non-numeric X)

🔐 Role-Based Token Filtering • Returns all expiring tokens for Admin users • Returns only user-owned expiring tokens for Limited users • Returns 403 if unauthenticated user tries to access the endpoint

🌐 REST API: GET /v1/apitoken/expiring • Returns 200 OK and correct token data for Admin user • Returns 200 OK and correct token data for Limited user • Returns empty array when no tokens are expiring • Returns 403 Forbidden when called without valid auth

[erickgonzalez]

View:

• Id Token
• User Id
• ExpiresDate
• issueDate

{
    "entity": {
        "tokens": [
            {
                "expiresDate": 1844834400000,
                "id": "apie3362144-8906-460d-b16e-e46a5bf69aef",
                "issueDate": 1750183464000,
                "userId": "dotcms.org.1",
            },
            {
                "expiresDate": 1844835400000,
                "id": "apie46a5bf69aef-8906-460d-asde-e46a5bf69aef",
                "issueDate": 1750183464000,
                "userId": "dotcms.org.1",
            },
}

[dsolistorres]

QA Passed: For Admin users, all the tokens that are expiring within the next 7 days are returned:

For limited users, only their tokens that are expiring in the next 7 days are returned:

A message is shown on login if expiring tokens are found. For limited users, the message is shown only if they have expiring tokens. For admin users, the message if there are expiring tokens for any users:

Also, an error is returned if a non-authenticated user tries to use the /api/v1/apitoken/expiring endpoint:

An error is returned if there is an invalid value for the EXPIRING_TOKEN_LOOKAHEAD_DAYS configuration parameter: