Enable customer automation

Beta Feature

The Enterprise Portal is Beta. Features described on this page are subject to change.

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.

Customer automation examples

The Workflow Guide component covers initial installation and polling for upgrades. The following examples show how customers can use the service account API from their own automation.

Automated upgrade pipeline

A customer's scheduled job can detect available releases, request update instructions, and apply an approved upgrade. Poll every 15 minutes to 1 hour.

GET /api/v1/releases/latest reads only the customer's assigned channel. If the license is pinned, it returns the pinned release. The optional channel_id parameter must match the assigned channel; any other channel returns 404.

GET /api/v1/versions lists installable versions on the assigned channel. Creating install options and PATCHing their version also resolve the version label on that channel.

The following examples use curl and jq in a Bash script. They assume the customer has already installed the application and retained its install options ID. Replace the placeholders, use the service account that owns that record, and complete each step before continuing. These snippets assume successful API responses and do not execute the generated instructions.

The API returns JSON errors as { "error": { "code": "...", "message": "..." } }. curl's -f flag suppresses HTTP error response bodies. To inspect an API error, run the curl request directly without -f or the jq version-extraction pipe.

Set the customer's Enterprise Portal origin, service account token, existing install options ID, and installed version:
```
export BASE_URL="https://your-enterprise-portal.example.com"
export SA_TOKEN="<service-account-token>"
export INSTALL_OPTIONS_ID="<existing-install-options-id>"
export INSTALLED_VERSION="<currently-installed-version-label>"
```
Use the version actually installed. GET /api/v1/install-options/{id} returns a version field. Use that field only if the customer's automation keeps it in sync with successful installations.
Poll for the latest available release and compare release.version_label:
```
export TARGET_VERSION=$(curl -fsS "$BASE_URL/api/v1/releases/latest" \
  -H "Authorization: Bearer $SA_TOKEN" | jq -r '.release.version_label')

if [ "$TARGET_VERSION" = "$INSTALLED_VERSION" ]; then
  echo "Already installed; no upgrade needed."
fi
```
For example, the response can contain:
```
{
  "release": {
    "version_label": "1.3.0",
    "release_sequence": 12,
    "created_at": "2026-07-15T12:00:00Z",
    "is_required": false,
    "release_notes": "Release notes for 1.3.0."
  }
}
```
release_notes is optional. A different version label identifies an available target. The customer's automation decides whether to approve and apply it.

If the labels match, no upgrade is needed; skip steps 3–5. Otherwise, check GET /api/v1/versions before choosing the next target. Read every page using page, page_size, and the response's pagination metadata. The latest response's release.is_required describes only that release. The update-instructions endpoint does not prevent skipping intermediate required releases.
```
curl -fsS "$BASE_URL/api/v1/versions?page=1&page_size=100" \
  -H "Authorization: Bearer $SA_TOKEN"
```
The versions list is newest first; use its returned order rather than sorting version labels. Find entries with is_required: true between the installed version and the latest target. Set TARGET_VERSION to each required entry's version and repeat steps 3–5, oldest first, before upgrading to the original latest target. After each successful upgrade, also update INSTALLED_VERSION. For example, if 1.2 is required, upgrade from 1.0 to 1.2, then to 1.3.

A pinned license lists only the pinned release. If the installed version or a required intermediate release is unavailable, ask the vendor to confirm the upgrade path and make the necessary releases accessible before proceeding. For more information about enforcement by installation method, see Required releases.
Request GET /api/v1/install-options/{id}/update-instructions?version=<target>:
```
curl -fsS --get "$BASE_URL/api/v1/install-options/$INSTALL_OPTIONS_ID/update-instructions" \
  -H "Authorization: Bearer $SA_TOKEN" \
  --data-urlencode "version=$TARGET_VERSION"
```
The version query parameter selects the target release, and the existing install options supply the installation configuration. This request does not apply the upgrade or change the saved version.
Follow steps[] in the response in order, including each step's description, commands, and downloads. Treat the generated content as opaque: do not hard-code step names, counts, commands, or artifact URLs. Steps vary by install type, network configuration, and release, and can include manual actions. If instructions are unavailable or empty, resolve the response message before continuing.

For steps[].downloads[].href, follow the returned URL. Relative URLs use the portal origin and service account token. Absolute URLs do not use that token. If a relative download redirects to object storage, follow the redirect without forwarding the token. If href is empty, check metadata.buildStatus and retry later.
After applying the upgrade and verifying success, record the installed version:
```
curl -fsS -X PATCH "$BASE_URL/api/v1/install-options/$INSTALL_OPTIONS_ID" \
  -H "Authorization: Bearer $SA_TOKEN" \
  -H "Content-Type: application/json" \
  --data "$(jq -n --arg version "$TARGET_VERSION" '{version: $version}')"
```
The PATCH request records the version. It does not deploy the release or verify success. Patching first would record the target as installed before the upgrade succeeds. If the upgrade fails, leave the saved version unchanged. If PATCH fails after a successful upgrade, retry recording the verified installed version before the next upgrade run.

Pre-stage airgap artifacts

A customer in an air-gapped environment can download release artifacts to an internal repository before a maintenance window. The upgrade then uses these staged assets.

A scheduled job uses the same GET /api/v1/releases/latest call and compares release.version_label against a separately tracked last-staged version. If the target needs staging, it calls GET /api/v1/install-options/{id}/update-instructions?version=<target>. It downloads the artifacts referenced in steps[].downloads[], pushes them to an internal artifact store, and can notify the operations team.

Include artifacts for any intermediate required releases identified in the upgrade path above.

Keep the install options version unchanged while pre-staging. Update the separate last-staged version after the downloads succeed. PATCH the install options only after applying and verifying the upgrade.

This pattern separates artifact retrieval from the upgrade itself, which is useful when the air-gapped network has a narrow transfer window or when artifacts need security scanning before deployment.

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:

---
title: API Reference
---

# API Reference

<APIReference />

---
title: Automation Workflow
---

# Automation Workflow

<HeadlessWorkflowGuide />

Then add them to your toc.yaml if they are not already there:

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:

<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[]
Polling the assigned channel for an available release and comparing its version label
Checking all pages of available versions and applying intermediate required releases in order
Fetching update instructions with the target version query parameter
Following the generated steps and recording the version after a successful upgrade

The workflow guide is an example, not a complete script. Customers must replace placeholder values and adapt the commands for their own automation.

Install examples reflect the install types enabled on the customer's license. The in-portal API reference documents the supported install types and request fields.

Customer authentication

Customer team admins create service account tokens from Team Settings > Service Accounts in the Enterprise Portal. API requests use this header:

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.

Team admins rotate or revoke tokens from Team Settings > Service Accounts in the Enterprise Portal. Rotating a token issues a new one and invalidates the old one, so any automation that authenticates with the token must be updated with the new value. For more information, see Rotate or revoke a service account token.

Why add automation docs​

Customer automation examples​

Automated upgrade pipeline​

Pre-stage airgap artifacts​

Add the default pages​

Customize the components​

What the API reference includes​

What the workflow guide includes​

Customer authentication​

On this page