Document Enterprise Portal service account automation

docs/vendor/enterprise-portal-v2-about.mdx

@@ -13,6 +13,7 @@ Content is driven by entitlements and channel assignment, so each customer sees
 ## What your customers can do
 
 - **Install and upgrade**: Step-by-step installation instructions for Helm and Embedded Cluster (Linux), with per-instance commands personalized to each customer's license and environment
+- **Automate installs and upgrades**: Service account API endpoints let customers create install profiles, fetch structured instructions, and download artifacts from CI/CD systems. For more information, see [Service account automation](/vendor/enterprise-portal-v2-service-account-automation).
 - **Manage instances**: View all deployed instances, check for available updates, and follow inline upgrade instructions
 - **Download install artifacts**: Download air gap bundles, Helm chart tarballs, and CLI tools directly from the portal. Available artifacts vary by install method and license entitlements
 - **Access security data**: Review CVE reports, filter to fixable vulnerabilities, view per-instance upgrade recommendations, and download SBOMs for each release. Available for Helm and Embedded Cluster installs when Security Center is enabled
@@ -28,6 +29,7 @@ The new Enterprise Portal is a complete rebuild of the customer portal experienc
 - **Content repo driven**: All portal content (pages, navigation, branding) is managed through a GitHub repo you control, not through Vendor Portal UI forms
 - **MDX components**: Interactive, customer-aware components (install commands, version selectors, upgrade paths) that adapt to each customer's license and instance state
 - **Versioned docs**: Each Git branch becomes a version in the customer's portal, with smart resolution that automatically finds the right content for any release
+- **Service account automation docs**: Built-in API reference and workflow guide components help customers automate install and upgrade workflows with service account tokens
 - **Local preview**: `replicated enterprise-portal preview` lets you preview the full portal locally with live reload
 - **Helm chart reference**: Auto-generated from your promoted releases with AI-enhanced descriptions
 - **Terraform module distribution**: License-gated module registry with native `terraform init` integration (premium feature)

docs/vendor/enterprise-portal-v2-service-account-automation.mdx

@@ -0,0 +1,127 @@
+---
+sidebar_label: Enable Customer Automation
+---
+
+# Enable customer automation
+
+:::important Alpha Feature
+Features described on this page are in alpha and subject to change. For access, contact your Replicated account representative.
+:::
+
+This topic describes how to add service account automation docs to the new Enterprise Portal. Service account automation lets your customers call Enterprise Portal API endpoints from CI/CD systems or other scripts.
+
+Customers can use these endpoints to create install profiles, get structured install and update instructions, and download referenced artifacts. The Enterprise Portal content template includes components that render customer-facing API documentation inside the customer's portal, so you can document automation without maintaining endpoint tables or example workflows by hand.
+
+## Why add automation docs
+
+Add service account automation docs when your customers need to install or update your application from automation.
+
+With these docs in the portal, customers can:
+
+- Find the API routes that are available from their Enterprise Portal domain
+- Learn how to authenticate with a customer service account token
+- Follow an example workflow for creating install options and fetching instructions
+- Download the Swagger JSON for the customer automation API
+- Download artifacts from the same links returned by the install instructions API
+
+These docs are customer-facing. They describe the Enterprise Portal API that runs from the customer's portal domain. They do not replace the Replicated Vendor API.
+
+## Add the default pages
+
+The default Enterprise Portal content template includes an **Automation** section.
+
+This section has API reference and workflow guide pages.
+
+You can keep these pages, move them, edit the surrounding text, or remove them from your content repo.
+
+The pages use two MDX components:
+
+- `<APIReference />`: Renders the service account API reference from Replicated's generated Swagger spec.
+- `<HeadlessWorkflowGuide />`: Renders an example workflow for using the API from automation.
+
+To add these pages to your own content repo, create pages like the following:
+
+```mdx
+---
+title: API Reference
+---
+
+# API Reference
+
+<APIReference />
+```
+
+```mdx
+---
+title: Automation Workflow
+---
+
+# Automation Workflow
+
+<HeadlessWorkflowGuide />
+```
+
+Then add them to your `toc.yaml` if they are not already there:
+
+```yaml
+navigation:
+  - title: Automation
+    icon: key
+    items:
+      - title: API Reference
+        page: pages/automation/api-reference.md
+      - title: Workflow Guide
+        page: pages/automation/workflow-guide.md
+```
+
+## Customize the components
+
+You can customize the text around these components like any other MDX content page. For example, you can add prerequisites, link to your support process, or include notes about how your customers should request service account access.
+
+The `<APIReference />` component also supports a `description` prop. Use it to replace the default intro text on the endpoint reference:
+
+```mdx
+<APIReference
+  description="Use the Acme service account API to create install profiles, fetch generated instructions, and download installation artifacts."
+/>
+```
+
+The `<HeadlessWorkflowGuide />` component does not support props. It renders the default example workflow from the Enterprise Portal template. To customize that page, edit the surrounding MDX content, move the component to a different page, or remove the component and write your own workflow.
+
+## What the API reference includes
+
+The API reference component documents the service account API endpoints that customers can call from the Enterprise Portal domain.
+
+The reference includes:
+
+- Release and version discovery endpoints
+- Install options create, list, get, and update endpoints
+- Install instruction and update instruction endpoints
+- Artifact download endpoints for generated instruction downloads
+- Plugin download endpoints
+- Request parameters, request body fields, response fields, accepted values, and error responses
+
+The component also includes a **Download Swagger JSON** button. Customers can use this file to inspect the API contract or import it into API tooling.
+
+## What the workflow guide includes
+
+The workflow guide shows an example automation sequence. It covers:
+
+- Setting the Enterprise Portal base URL and service account token
+- Listing available versions
+- Creating install options
+- Fetching structured install instructions
+- Downloading artifacts from `steps[].downloads[]`
+- Updating install options before fetching instructions again
+
+The workflow guide is an example, not a complete script. Customers must replace placeholder values and adapt the commands for their own automation.
+
+## Customer authentication
+
+Customer team admins create service account tokens from **Team Settings > Service Accounts** in the Enterprise Portal. API requests use this header:
+
+```bash
+Authorization: Bearer <service-account-token>
+```
+
+Browser portal sessions and service account tokens are separate authentication methods. Customers should store service account tokens securely and rotate them when needed.

docs/vendor/enterprise-portal-v2-use.mdx

@@ -85,6 +85,16 @@ Customer team admins can manage their portal team from the Team Settings page:
 - **Service accounts**: Create and manage service accounts for programmatic access (CI/CD, automation)
 - **SAML configuration**: When SAML is enabled by the vendor, admins can configure their identity provider by uploading IdP metadata and certificates
 
+## Service account automation
+
+Customer team admins can create service account tokens for CI/CD systems and other automation.
+
+Customers can use these tokens to call Enterprise Portal API endpoints from the same domain as the portal.
+
+The default Enterprise Portal content template includes an API reference and workflow guide for service account automation.
+
+For more information, see [Service account automation](/vendor/enterprise-portal-v2-service-account-automation).
+
 ## Support bundles
 
 Customers can generate and upload support bundles from the portal:
@@ -108,4 +118,3 @@ Security Center data is available for Helm and Embedded Cluster installations on
 ## License information
 
 Customers can view their license details including expiration date, license type, assigned channel, and any custom license fields configured by the vendor. This information is accessible from the portal but is read-only for customers.
-

sidebars.js

@@ -215,6 +215,7 @@ const sidebars = {
         "vendor/enterprise-portal-v2-emails",
         "vendor/enterprise-portal-v2-branding",
         "vendor/enterprise-portal-v2-content",
+        "vendor/enterprise-portal-v2-service-account-automation",
         "vendor/enterprise-portal-v2-versioned-docs",
         "vendor/enterprise-portal-v2-helm-reference",
         "vendor/enterprise-portal-v2-terraform",