Skip to main content

Enable customer automation

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:

---
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[]
  • 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:

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.

On this page