Epic Goal

Update the official Red Hat Quay user documentation to guide administrators through the new "API Access Tokens" UI workflow, enabling them to manage tokens visually and migrate from legacy long-lived tokens to modern rotating tokens.

Why is this important?

This feature changes a core workflow that users have been accustomed to for years.  Users who previously used the "Generate Token" button need guidance on the new tab structure. 

The UI also provides the primary migration path for transitioning legacy tokens to modern tokens with proper expiration policies.

Scenarios

• The Migrator: An admin reads the User Guide to understand how to safely replace a 5-year-old legacy token without breaking production.

• The Auditor: A security officer reads the docs to understand what the "Last Used" timestamp represents and how reliable it is 
  for identifying unused tokens.

• The New User: A first-time Quay admin follows the step-by-step guide to create their first API token with proper expiration settings. 

• The Security Admin: An admin reviews the security best practices to establish token expiration policies for their organization.

Acceptance Criteria

User Guide Update:

• Replace old "Generate Token" screenshots with the new "API Access Tokens" tab. 

• Explain the new columns:
  • Name - User-defined identifier for the token
  • Created By - Who created the token
  • Scopes - What permissions the token has
  • Expires - When the token expires
  • Last Used - When the token was last used for API authentication

• Step-by-step instructions for:
  • Navigating to the "API Access Tokens" tab
  • Creating a new token with expiration
  • Copying the token secret securely
  • Revoking a token

Migration Guide:

• Identifying legacy tokens:
  • How to recognize legacy tokens in the list (Name: "Legacy Token")
  • Understanding legacy token expiration dates

• Step-by-step migration process:
  1. Open "API Access Tokens" tab for the application
  2. Identify the legacy token to replace
  3. Click "Generate New Token"
  4. Configure name, expiration (e.g., 90 days), and scopes
  5. Copy the new token secret
  6. Update CI/CD system or script with new token
  7. Verify new token works correctly
  8. Return to UI and revoke the legacy token

• Rollback guidance:
  • What to do if the new token doesn't work
  • How to create another token if needed

Security Best Practices

• Token expiration recommendations:
  • When to use "No Expiration" (long-lived bootstrap tokens)
  • When to use short expiration (30-90 days for scripts)
  • Token rotation strategies

• Warning boxes:
  • Risks of "No Expiration" tokens
  • Importance of the "Last Used" column for security audits
  • Never share token secrets via insecure channels

Deprecation Notice

• Clearly mark old "Generate Token" workflow as deprecated
• Redirect users to new "API Access Tokens" tab documentation
• Explain that existing tokens continue to work (no forced migration)

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

Dependencies (internal and external)

• Internal: Access to the Staging/Dev environment to capture new UI screenshots.
• Internal: Finalized UI design from Phase 2 UI Epic (PROJQUAY-9857).
• Internal: Phase 1 documentation (PROJQUAY-10437) complete (i.e., API reference).

Previous Work (Optional):

1. Existing "Using OAuth" documentation page.
2. Existing "Managing Applications" documentation

Open questions:

• Should migration guidance be its own page or embedded in the main user guide?

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-10437: Phase 1 documentation complete (i.e., API reference).
• The original shared document: PROJQUAY-9755: Granular lifecycle management for OAuth 2 application tokens