Feature Overview (aka. goal summary)

This feature enables fully automated Quay deployments by providing a programmatic way to create OAuth API tokens without requiring UI interaction. This addresses the "catch-22" problem where token creation currently requires a pre-existing token or interactive UI session.

This is Phase 1 of the OAuth token lifecycle improvements, focusing on the API and backend infrastructure required for automation workflows.

Goals (aka. expected user outcomes)

• Zero-touch token provisioning: Enable CI/CD systems and automation tools to create OAuth tokens without any prior UI interaction.

• Secure bootstrap authentication: Provide alternative authentication methods (Basic Auth for superusers, LDAP service accounts, OIDC service principals) for initial token creation.

• Security by default: The zero-touch capability is disabled by default and must be explicitly enabled via configuration.

• Token lifecycle API: Expose POST (create), GET (list), and DELETE (revoke) endpoints for programmatic token management.

• Support automation tools: Return tokens in formats easily consumable by automation workflows.

Background

Currently, to automate Quay via its API, an OAuth Application must be created first to mint an API token. This can only be done via the Quay UI today, which presents a barrier for:

• Fully automated Quay deployments (e.g., GitOps workflows)
• CI/CD pipelines that need to bootstrap Quay access
• Air-gapped or headless environments without UI access

The existing `FEATURE_USER_INITIALIZE` provides a partial solution but yields tokens limited to 150 minutes, which is insufficient for long-term automation.

This feature provides a secure, configurable mechanism to create tokens programmatically while maintaining security through feature flags and proper authentication.

Requirements (Acceptance criteria)

Epic 1: PROJQUAY-9856 [Backend] API & Authentication for Programmatic Token Provisioning

• Database schema supporting multiple tokens per OAuth Application
• API endpoints: POST/GET/DELETE for token lifecycle

• Standard Authentication: OAuth Bearer Token or Session Cookie
• Zero-Touch Bootstrap Authentication (when `FEATURE_PROGRAMMATIC_BOOTSTRAP=true`):
  • HTTP Basic Auth for superusers
  • LDAP service account authentication (via `LDAP_SUPERUSER_FILTER`)
  • OIDC service principal authentication

• Feature flag: `FEATURE_PROGRAMMATIC_BOOTSTRAP` (default: `false`)
• Audit logging for all zero-touch bootstrap authentication attempts

Epic 2: PROJQUAY-10437 [Docs] API Documentation for Programmatic Token Provisioning

• API Reference for POST/GET/DELETE endpoints
• Zero-Touch Bootstrap Guide
• Configuration guide for `FEATURE_PROGRAMMATIC_BOOTSTRAP`
• Security best practices
• Some curl examples

Feature Flags

API Endpoints

• POST /api/v1/organization/{orgname}/application/{client_id}/tokens
  • Creates a new token with optional expiration and scopes
  • Auth: Standard (OAuth/Session) or Zero-Touch Bootstrap (Basic Auth/LDAP/OIDC when enabled)
  • Returns: Token secret (shown only once)

• GET /api/v1/organization/{orgname}/application/{client_id}/tokens
  • Lists all tokens with metadata (excluding secrets)
  • Auth: Standard (OAuth/Session) only

• DELETE /api/v1/organization/{orgname}/application/{client_id}/tokens/{token_id}
  • Immediately revokes a specific token
  • Auth: Standard (OAuth/Session) only

Reference

• Design document: Granular lifecycle management for OAuth 2 application