Epic Goal

Create a user-friendly interface within the "Manage OAuth Application" modal that allows users to visualize their token inventory, identify legacy tokens, generate new tokens with expiration dates, and revoke them safely.

Why is this important?

The UI is the primary migration path for most users.  It provides the visibility users currently lack, allowing them to confidently transition from legacy long-lived tokens to modern rotating tokens without needing to write API scripts first.

While Phase 1 delivered the API for automation users, Phase 2 delivers the UI for administrators who prefer visual management.

Scenarios

• Migration: User opens the tab, sees a "Legacy Token" (Expires in 2029), creates a new replacement token, 
  and safely revokes the legacy one after verifying the new token works.

• Creation: User generates a token for "Jenkins Prod," sets it to expire in 90 days, and copies the secret to the clipboard.

• Monitoring: User checks the list to see if the "Test Script" token has been used recently (checking Last Used column) to identify unused tokens for cleanup.

• Security audit: Admin reviews all tokens for an application to identify any with "No Expiration" that should be rotated.  

Acceptance Criteria

1) Navigation:

• New "API Access Tokens" tab replaces "Generate Token" in the OAuth Application modal.
• Tab is accessible via: "Organizations → [Select Org] → OAuth Applications → [Click App Name]"
• Modal tabs: "Settings | OAuth Information | API Access Tokens (new)"

2) Token List:

• Displays all active tokens (legacy and new) for the application.
• Columns:
  • Name - User-defined name (or "Legacy Token" for pre-existing)
  • Created By - Username who created the token (or "Unknown" for legacy)
  • Scopes - Summary of permissions (with tooltip for long lists)
  • Created - Timestamp of token creation
  • Expires - Expiration date (or "Never" / legacy date)
  • Last Used - Timestamp of last API call (or "Never used")
  • Actions - Kebab menu with "Revoke" option

3) Generate New Token Button:

• Located at the top of the "API Access Tokens" tab
• Opens "Generate New Token" wizard modal

*4) Generate New Token Wizard

• Token Name (Required): Free-text input (e.g., "Jenkins production build")

• Expiration (Required): Dropdown with options:
  • 7 days
  • 30 days
  • 90 days
  • 1 year
  • 10 years (default - matches current behavior)
  • No expiration

• Scopes(Required): Checklist of permissions
  • Defaults to the least-permissive scope
  • Same scope options as legacy "Generate Token" tab

• "Generate" button creates token and displays secret
• Token secret displayed only once with a prominent warning
• "Copy to clipboard" button provided
• Warning message: "This is the only time this token will be shown. Copy it and store it in a secure location."

5) Legacy Token Handling:

• Pre-existing tokens appear in the list with:
  • Name: "Legacy Token" (non-editable)
  • Created By: "Unknown" (if not tracked)
  • Expires: Original 10-year expiration date
• Legacy tokens can be revoked like any other token

6) Revoke Action:

• "Revoke" option in Actions kebab menu
• Triggers confirmation modal: "Are you sure you want to revoke the token '[token_name]'? This action cannot be undone."
• Upon confirmation, the token is immediately revoked
• Token removed from the list after successful revocation

7) Security & UX:

• Token secret is never displayed after initial creation
• Revocation requires explicit confirmation
• Loading states for API calls
• Error handling with user-friendly messages

• CI - MUST be running successfully with tests automated
• Release Technical Enablement - Provide necessary release enablement details and documents.

Dependencies (internal and external)

Internal:

• Blocked by: Phase 1 Backend API (PROJQUAY-9856 must be available for data fetching)
• API endpoints: GET/POST/DELETE `/api/v1/organization/ {orgname}/application/ {client_id}/tokens`

Previous Work (Optional):

1. Existing "Generate Token" tab (to be deprecated/removed).
2. Existing OAuth Application modal structure
3. Existing React component patterns in `web/src/routes/OrganizationsList/`

Open questions:

• How do we display the scopes column if the list is very long? (Tooltip vs Truncation vs. Expandable).
• Should we show a "migration wizard" that guides users through replacing legacy tokens?
• Should the token list support sorting/filtering?
• Do we need pagination if an application has many tokens?

Done Checklist

• CI - CI is running, tests are automated and merged.
• Release Enablement <link to Feature Enablement Presentation>
• DEV - Upstream code and tests merged: <link to meaningful PR or GitHub Issue>
• DEV - Upstream documentation merged: <link to meaningful PR or GitHub Issue>
• DEV - Downstream build attached to advisory: <link to errata>
• QE - Test plans in Polarion: <link or reference to Polarion>
• QE - Automated tests merged: <link or reference to automated tests>
• DOC - Downstream documentation merged: <link to meaningful PR>

Reference 

For the full collaborative design spec, background history, and detailed edge cases, please see:

• RFE-4324 - Manage OAuth tokens and their permissions in UI and API
• Depends on: PROJQUAY-9856 Phase 1 Backend API
• the original shared document: PROJQUAY-9755: Granular lifecycle management for OAuth 2 application tokens