Rendering Guides - Stackone

Guides live in the connector YAML under support.guides, so they ship and version with the connector instead of going stale in a separate docs site while the connector changes. Fetch them from the API to render in your own product.

support and Guides

The schema: sections, steps, warnings, images, and scope filtering.

Fetch the guides

Guides come back from GET /actions when you ask for them:

curl -X GET "https://api.stackone.com/actions?include=authentication_guides&filter[connectors]=[provider]" \
  -H "Authorization: Basic $(echo -n 'YOUR_API_KEY:' | base64)"

Parameter	Description
`include=authentication_guides`	Returns `support.guides` for each authentication method
`include=event_guides`	Returns the event guides from `events.guides`
`include=action_details`	Returns extended action metadata
`filter[connectors]`	Restrict to one connector key, such as `filter[connectors]=bamboohr`
`page_size`	Results per page
`next`	Pagination cursor from the previous response

GET /actions

Full parameter and response reference.

Response shape

Guides are nested per authentication method, since each method needs different instructions:

{
  "data": [
    {
      "key": "your_provider",
      "name": "Your Provider",
      "authentication": [
        {
          "type": "custom",
          "label": "API Key",
          "key": "api_key",
          "configFields": [
            { "key": "apiKey", "label": "API Key", "type": "password", "required": true }
          ],
          "support": {
            "guides": {
              "config": {
                "warning": "Admin access required to generate an API key.",
                "sections": [
                  {
                    "title": "Generating an API Key",
                    "content": "Generate an API key from your admin dashboard.",
                    "steps": [
                      {
                        "title": "Sign in and open API settings",
                        "content": "Sign in to your Provider account.",
                        "list": [
                          "Click **Settings** in the top navigation",
                          "Select **API** from the sidebar",
                          "Click **Create API Key**"
                        ]
                      }
                    ]
                  }
                ]
              }
            }
          }
        }
      ],
      "actions": [
        {
          "id": "your_provider_list_employees",
          "label": "List Employees",
          "required_scopes": ["employees:read"]
        }
      ]
    }
  ],
  "next": null
}

Render in your own UI

Fetch and parse

The shape is small enough to type by hand. title and content are always present; everything else is optional:

interface GuideImage {
  src: string;
  alt: string;
}

interface GuideStep {
  title: string;
  content: string;
  list?: string[];
  image?: GuideImage;
  /** Space-separated scope names, not an array */
  applicableScopes?: string;
  /** Render badges for the actions these scopes unlock */
  displayScopes?: boolean;
}

interface GuideSection {
  title: string;
  content: string;
  list?: string[];
  image?: GuideImage;
  steps?: GuideStep[];
  applicableScopes?: string;
}

interface AuthGuides {
  config?: { warning?: string; sections: GuideSection[] };
  setup?: { warning?: string; sections: GuideSection[] };
}

async function fetchConnectorGuides(
  connectorKey: string,
  apiKey: string,
  authMethodKey?: string,
): Promise<AuthGuides> {
  const authHeader = Buffer.from(`${apiKey}:`).toString("base64");

  const response = await fetch(
    `https://api.stackone.com/actions?include=authentication_guides&filter[connectors]=${connectorKey}`,
    { headers: { Authorization: `Basic ${authHeader}` } },
  );

  const { data } = await response.json();
  const connector = data?.find((c: any) => c.key === connectorKey);

  if (!connector) {
    throw new Error(`Connector "${connectorKey}" not found`);
  }

  const auth = authMethodKey
    ? connector.authentication?.find((a: any) => a.key === authMethodKey)
    : connector.authentication?.[0];

  return auth?.support?.guides ?? {};
}

In the browser, swap Buffer.from(...) for btoa($:).

Render content

content and list items contain markdown: links, bold for UI labels, backticks for URLs and values. Render them through a markdown component such as react-markdown and sanitize the output. Building HTML strings by hand and injecting them with dangerouslySetInnerHTML puts provider-authored text straight into your DOM.

import ReactMarkdown from "react-markdown";

function Section({ section }: { section: GuideSection }) {
  return (
    <section>
      <h3>{section.title}</h3>
      <ReactMarkdown>{section.content}</ReactMarkdown>

      {section.list && (
        <ul>
          {section.list.map((item) => (
            <li key={item}>
              <ReactMarkdown>{item}</ReactMarkdown>
            </li>
          ))}
        </ul>
      )}

      {section.image && <img src={section.image.src} alt={section.image.alt} />}

      {section.steps?.map((step) => (
        <div key={step.title}>
          <h4>{step.title}</h4>
          <ReactMarkdown>{step.content}</ReactMarkdown>
        </div>
      ))}
    </section>
  );
}

Filter by scope

applicableScopes marks a section or step as relevant only to certain scopes, so a read-only integration isn’t told to grant write access. It’s a space-separated string, so split it before comparing:

function appliesTo(scopes: string | undefined, selected: string[]): boolean {
  if (!scopes) {
    return true;
  }
  return scopes.split(/\s+/).some((scope) => selected.includes(scope));
}

const visible = sections.filter((section) => appliesTo(section.applicableScopes, selected));

A section with no applicableScopes always shows. Steps carry the same field, so filter them the same way.

YAML Schema

The guide, section, and step fields in full.

support and Guides

​Fetch the guides

GET /actions

​Response shape

​Render in your own UI

​Related

YAML Schema

Fetch the guides

Response shape

Render in your own UI

Related