Epic Goal

 
Create comprehensive API documentation that enables DevOps engineers and platform teams to programmatically provision OAuth tokens for automation workflows, including the zero-touch bootstrap pattern for fully automated Quay deployments.

Why is this important?

The API features delivered in Phase 1 are invisible without documentation.  The "Zero-Touch Bootstrap Pattern" is a new capability that requires clear guidance to drive adoption.  Platform engineers need curl examples and security guidance to successfully implement automated Quay deployments.

Scenarios

• The Automator: A DevOps engineer searches the API docs to find out how to programmatically create a token with a 30-day expiration for their Jenkins pipeline.

• The Zero-Touch Deployer: A platform engineer deploying Quay in a fully automated environment reads the Configuration Guide to understand how to enable FEATURE_PROGRAMMATIC_BOOTSTRAP and use Basic Auth to create the initial token without any UI interaction.

• The Enterprise Admin: An admin with an existing LDAP infrastructure reads the Automation Guide to understand how their LDAP service account (matching LDAP_SUPERUSER_FILTER) can be used for zero-touch token creation.

Acceptance Criteria

API Reference Documentation

• Document POST endpoint: `POST /api/v1/organization/ {orgname}/application/{client_id}/tokens`
  • Request payload: `name`, `expiration`, `scopes`
  • Response format: `token_secret`
  • Authentication options (standard and zero-touch bootstrap)

• Document GET endpoint: `GET /api/v1/organization/{orgname}/application/{client_id}/tokens`
  • Response format: Array of token metadata
  • Pagination (if implemented)

• Document DELETE endpoint: `DELETE /api/v1/organization/{orgname}/application/{client_id}/tokens/ {token_id}`
  • Response: 204 No Content

• Include request/response examples for all endpoints

Configuration Guide

• Document `FEATURE_PROGRAMMATIC_BOOTSTRAP` feature flag
  • Default value: `false`
  • Security implications
  • When to enable

• Document-related configuration options:
  • `SUPER_USERS` list (required for Basic Auth - user must be in this list)
  • `LDAP_SUPERUSER_FILTER` (for LDAP service accounts)
  • `SUPER_USERS` list

• Document rate limiting (reference existing `FEATURE_RATE_LIMITS`)

Zero-Touch Bootstrap Guide

• Prerequisites section:
  • `FEATURE_PROGRAMMATIC_BOOTSTRAP: true` in config.yaml
  • For Basic Auth: User must be in `SUPER_USERS` list (note: `FEATURE_DIRECT_LOGIN` is NOT required)
  • For LDAP: Service account matching `LDAP_SUPERUSER_FILTER`
  • For OIDC: Configured OIDC provider with service principal

• Step-by-step guide:
  • Step 1: Configure Quay with feature flag enabled
  • Step 2: Authenticate via chosen method (Basic Auth / LDAP / OIDC)
  • Step 3: Create initial bootstrap token via API
  • Step 4: Use bootstrap token for subsequent operations

• curl examples for each authentication method:

  # Using Basic Auth (Superuser credentials)
  curl -u admin:password -X POST \
    -H "Content-Type: application/json" \
    -d '{"name": "bootstrap-token", "expiration": "365d", "scopes": ["org:admin"]}' \
    https://quay.example.com/api/v1/organization/myorg/application/app123/tokens
  
  # Using LDAP Service Account
  curl -u ldap-service-account:password -X POST \
    -H "Content-Type: application/json" \
    -d '{"name": "automation-token", "expiration": "30d", "scopes": ["repo:read", "repo:write"]}' \
    https://quay.example.com/api/v1/organization/myorg/application/app123/tokens
  

Standard Bootstrap Guide (Using Existing Token)

• Scenario: Bootstrap via UI-created token then API:
  • Step 1: Create long-lived "Bootstrap Token" via UI (one-time setup)
  • Step 2: Use that token to script creation of short-lived tokens
  • curl examples using Bearer token authentication

     # Using existing OAuth Bearer Token (standard authentication)
    curl -H "Authorization: Bearer <existing-token>" -X POST \
    -H "Content-Type: application/json" \
    -d ' \{"name": "ci-job-token", "expiration": "1h", "scopes": ["repo:read"]}
    ' \
    [https://quay.example.com/api/v1/organization/myorg/application/app123/tokens]
    

Security Best Practices

• Warning boxes for:
  • "No Expiration" token risks
  • `FEATURE_PROGRAMMATIC_BOOTSTRAP` security implications
  • Credential storage recommendations

• Guidance on token rotation strategies
• Audit logging and monitoring recommendations

Troubleshooting

• Common zero-touch bootstrap authentication errors:
  • 401 when user is not in `SUPER_USERS` list (for Basic Auth)
  • 401 when LDAP service account not matching `LDAP_SUPERUSER_FILTER`
  • 403 when user lacks Organization Admin permission for the target org

• Rate limiting errors (429) and resolution

Dependencies (internal and external)

• Internal: 
  • Finalized API Spec (Swagger/OpenAPI) from the Backend engineering team
  • Feature flag names confirmed
  • Access to staging/dev environment for testing examples

Previous Work (Optional):

1. Existing "Using OAuth" documentation page.
2. Existing API documentation structure.

Open questions:

• Should the Zero-Touch Bootstrap Guide be its own page or a subsection of the API 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-4345: Provisioning Quay API tokens programmatically
• RFE-8731: API tokens for bootstrapping and automating Quay deployments
• The original shared document: PROJQUAY-9755: Granular lifecycle management for OAuth 2 application tokens