> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Field reference for a connector's authentication types.

# Structure

Multiple authentication methods per connector are allowed.

```yaml theme={null}
authentication:
  # Authentication using OAuth
  - oauth2:
      type: oauth2
      label: OAuth 2.0
      # ...remaining oauth2 fields
  # Authentication using API key
  - api_key:
      type: custom
      label: API Key
      # ...remaining custom fields
```

# Properties

Authentication methods the connector supports.

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>[`authorization`](#authorization)</td>
      <td>Runtime authorization strategy applied to outgoing requests.</td>
      <td>union</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>[`certificates`](#certificates)</td>
      <td>Mutual-TLS certificates and keys for this method.</td>
      <td>object</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`configFields`](#configfields)</td>
      <td>Credentials the end-user enters when linking an account.</td>
      <td>array</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`configNotices`](#confignotices)</td>
      <td>Callouts shown while entering config fields.</td>
      <td>object\[]</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`environments`](#environments)</td>
      <td>Deployment targets selectable for this method.</td>
      <td>object\[]</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`grantType`</td>
      <td>OAuth grant flow used to obtain tokens.<br />Allowed: `authorization_code`, `client_credentials`<br />Default: `authorization_code`</td>
      <td>enum</td>
      <td>No</td>
    </tr>

    <tr>
      <td>`label`</td>
      <td>Display name for this authentication method.</td>
      <td>string</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>[`refreshAuthentication`](#refreshauthentication)</td>
      <td>Configuration for refreshing expired credentials.</td>
      <td>object</td>
      <td>No</td>
    </tr>

    <tr>
      <td>`releaseStage`</td>
      <td>Maturity level of this authentication method. Defaults to the highest stage among the actions and events it can run.<br />Allowed: `preview`, `beta`, `ga`, `deprecated`, `internal`</td>
      <td>enum</td>
      <td>No</td>
    </tr>

    <tr>
      <td>`requiredScopes`</td>
      <td>Scope names required by this authentication method. Space-separated, with any name that contains spaces wrapped in double quotes.</td>
      <td>string</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`setupFields`](#setupfields)</td>
      <td>Credentials entered when creating a Connector Profile.</td>
      <td>array</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`setupNotices`](#setupnotices)</td>
      <td>Callouts shown while entering setup fields.</td>
      <td>object\[]</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`support`](#support)</td>
      <td>Help resources shown while connecting with this method.</td>
      <td>object</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`testActions`](#testactions)</td>
      <td>Actions run to validate a connection after authentication.</td>
      <td>object\[]</td>
      <td>No</td>
    </tr>

    <tr>
      <td>`type`</td>
      <td>Selects the OAuth 2.0 authentication method.</td>
      <td>string</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>[`authorizationFlow`](#authorizationflow)</td>
      <td>MCP OAuth authorization flow; static credentials are used when omitted.</td>
      <td>object</td>
      <td>No</td>
    </tr>
  </tbody>
</table>

The variants share a common set of fields and are told apart by `type`.

<Tabs>
  <Tab title="oauth2">
    The `grantType` field selects the OAuth grant flow, either `authorization_code` (default) or `client_credentials`.

    ```yaml theme={null}
    authentication:
      - oauth2:
          type: oauth2
          label: OAuth 2.0
          grantType: authorization_code
          authorization: { ... }
          environments: [ ... ]
          # ...remaining fields
    ```
  </Tab>

  <Tab title="custom">
    The general-purpose method, for providers whose authentication doesn't fit `oauth2`, `oidc`, or `mcp`.

    ```yaml theme={null}
    authentication:
      - api_key:
          type: custom
          label: API Key
          authorization: { ... }
          environments: [ ... ]
          # ...remaining fields
    ```
  </Tab>

  <Tab title="oidc">
    Runs the authorization-code flow using standard OpenID Connect discovery.

    ```yaml theme={null}
    authentication:
      - oidc:
          type: oidc
          label: OpenID Connect
          authorization: { ... }
          environments: [ ... ]
          # ...remaining fields
    ```
  </Tab>

  <Tab title="mcp">
    Authenticates against a remote MCP server. The optional `authorizationFlow` field runs the MCP OAuth sequence when present, and falls back to static credentials like `custom` when omitted.

    ```yaml theme={null}
    authentication:
      - mcp:
          type: mcp
          label: MCP Server
          authorizationFlow:
            clientRegistration: dcr
            scopes: [read, write]
          authorization: { ... }
          environments: [ ... ]
          # ...remaining fields
    ```
  </Tab>
</Tabs>

## authorization

Runtime authorization strategy applied to outgoing requests.

<Tabs>
  <Tab title="none">
    <table>
      <colgroup>
        <col width="210" />

        <col width="400" />

        <col width="90" />

        <col width="90" />
      </colgroup>

      <thead>
        <tr>
          <th>Field</th>
          <th>Description</th>
          <th>Type</th>
          <th>Required</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>`redirectUri`</td>
          <td>OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>[`signing`](#authorization-none-signing)</td>
          <td>Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.</td>
          <td>union</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`type`</td>
          <td>Sends requests without an authorization header.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>
      </tbody>
    </table>

    <AccordionGroup>
      <Accordion title="authorization.none.signing">
        Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.

        <Tabs>
          <Tab title="aws4">
            <table>
              <colgroup>
                <col width="210" />

                <col width="400" />

                <col width="90" />

                <col width="90" />
              </colgroup>

              <thead>
                <tr>
                  <th>Field</th>
                  <th>Description</th>
                  <th>Type</th>
                  <th>Required</th>
                </tr>
              </thead>

              <tbody>
                <tr>
                  <td>`region`</td>
                  <td>AWS region used in the signing credential scope. Falls back to the credential region or `us-east-1` when omitted.</td>
                  <td>string</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>`service`</td>
                  <td>AWS service name used in the signing credential scope. For example `s3` or `execute-api`.</td>
                  <td>string</td>
                  <td>Yes</td>
                </tr>

                <tr>
                  <td>`strategy`</td>
                  <td>Signs requests with AWS Signature Version 4.</td>
                  <td>string</td>
                  <td>Yes</td>
                </tr>
              </tbody>
            </table>
          </Tab>

          <Tab title="hmac">
            <table>
              <colgroup>
                <col width="210" />

                <col width="400" />

                <col width="90" />

                <col width="90" />
              </colgroup>

              <thead>
                <tr>
                  <th>Field</th>
                  <th>Description</th>
                  <th>Type</th>
                  <th>Required</th>
                </tr>
              </thead>

              <tbody>
                <tr>
                  <td>`algorithm`</td>
                  <td>Hash algorithm for the HMAC signature. Defaults to `sha256`.<br />Allowed: `sha1`, `sha256`, `sha512`</td>
                  <td>enum</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>`dateFormat`</td>
                  <td>Timestamp format used in the signed string. Either `iso8601` (default) or `rfc2822`.<br />Allowed: `iso8601`, `rfc2822`</td>
                  <td>enum</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>`headerName`</td>
                  <td>Header the signature is written into. Defaults to `X-Signature`.</td>
                  <td>string</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>`includeBodyHash`</td>
                  <td>Hash the request body into the signed string, defaulting to `true`. When `false`, form-urlencoded body params are folded into the canonical string instead.</td>
                  <td>boolean</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>`includeHost`</td>
                  <td>Include the request hostname in the signed canonical string. Defaults to `false`.</td>
                  <td>boolean</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>`outputFormat`</td>
                  <td>Where the signature is emitted. `header` writes a signature header and `basic` writes an HTTP Basic `Authorization` header.<br />Allowed: `header`, `basic`</td>
                  <td>enum</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>`prefix`</td>
                  <td>Prefix prepended to the signature value in the header. Defaults to `hmac-&lt;algorithm&gt;`.</td>
                  <td>string</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>`strategy`</td>
                  <td>Signs requests with an HMAC signature over a canonical request string.</td>
                  <td>string</td>
                  <td>Yes</td>
                </tr>

                <tr>
                  <td>`username`</td>
                  <td>Username paired with the signature when `outputFormat` is `basic`.</td>
                  <td>string</td>
                  <td>No</td>
                </tr>
              </tbody>
            </table>
          </Tab>
        </Tabs>
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="basic">
    <table>
      <colgroup>
        <col width="210" />

        <col width="400" />

        <col width="90" />

        <col width="90" />
      </colgroup>

      <thead>
        <tr>
          <th>Field</th>
          <th>Description</th>
          <th>Type</th>
          <th>Required</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>`encoding`</td>
          <td>Encoding applied to the `username:password` pair. Defaults to `base64`.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`password`</td>
          <td>Password for HTTP Basic authentication.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`redirectUri`</td>
          <td>OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`type`</td>
          <td>Configures HTTP Basic authentication.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`username`</td>
          <td>Username for HTTP Basic authentication.</td>
          <td>string</td>
          <td>No</td>
        </tr>
      </tbody>
    </table>
  </Tab>

  <Tab title="bearer">
    <table>
      <colgroup>
        <col width="210" />

        <col width="400" />

        <col width="90" />

        <col width="90" />
      </colgroup>

      <thead>
        <tr>
          <th>Field</th>
          <th>Description</th>
          <th>Type</th>
          <th>Required</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>`includeBearer`</td>
          <td>Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`.<br />Default: `true`</td>
          <td>boolean</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`redirectUri`</td>
          <td>OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`token`</td>
          <td>Token sent on each request. Supports expressions.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`type`</td>
          <td>Configures bearer token authentication.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>
      </tbody>
    </table>
  </Tab>

  <Tab title="oauth2">
    <table>
      <colgroup>
        <col width="210" />

        <col width="400" />

        <col width="90" />

        <col width="90" />
      </colgroup>

      <thead>
        <tr>
          <th>Field</th>
          <th>Description</th>
          <th>Type</th>
          <th>Required</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>`additionalTokenFields`</td>
          <td>Extra credential fields to read from the token endpoint response. Each key is a credential name and each value an expression.</td>
          <td>object</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`authorizationParams`</td>
          <td>Extra query parameters appended to the authorization URL. Values support expressions.</td>
          <td>object</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`authorizationUrl`</td>
          <td>Provider authorization endpoint where the user grants access.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`callbackParams`</td>
          <td>Maps OAuth callback query parameter names to the credential keys their values are stored under. Cannot target reserved credential keys.</td>
          <td>object</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`customHeaders`</td>
          <td>Additional HTTP headers sent with token endpoint requests.</td>
          <td>object</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`includeBearer`</td>
          <td>Prefix the token with `Bearer ` in the `Authorization` header. Defaults to `true`.<br />Default: `true`</td>
          <td>boolean</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`issuer`</td>
          <td>OpenID Connect issuer identifier for the provider.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`pkce`</td>
          <td>Enable PKCE for the authorization code flow.</td>
          <td>boolean</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`redirectUri`</td>
          <td>Overrides the OAuth callback URL. The computed callback URL can be seen on the connector profile.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`scopeDelimiter`</td>
          <td>Delimiter used to separate scopes when requesting authorization.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`scopes`</td>
          <td>OAuth scopes requested during authorization.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`token`</td>
          <td>Expression that resolves the access token sent on each request.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`tokenExpiresIn`</td>
          <td>Access token lifetime in seconds.</td>
          <td>number</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`tokenParams`</td>
          <td>Extra parameters sent to the token endpoint. Values support expressions.</td>
          <td>object</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`tokenRefreshExpiresIn`</td>
          <td>Refresh token lifetime in seconds.</td>
          <td>number</td>
          <td>No</td>
        </tr>

        <tr>
          <td>[`tokenResponse`](#authorization-oauth2-tokenresponse)</td>
          <td>Adjusts how a non-standard token endpoint response is parsed.</td>
          <td>object</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`tokenUrl`</td>
          <td>Provider token endpoint used to exchange the authorization code and to refresh tokens.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`type`</td>
          <td>Configures OAuth 2.0 authentication.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>
      </tbody>
    </table>

    <AccordionGroup>
      <Accordion title="authorization.oauth2.tokenResponse">
        Adjusts how a non-standard token endpoint response is parsed.

        <table>
          <colgroup>
            <col width="210" />

            <col width="400" />

            <col width="90" />

            <col width="90" />
          </colgroup>

          <thead>
            <tr>
              <th>Field</th>
              <th>Description</th>
              <th>Type</th>
              <th>Required</th>
            </tr>
          </thead>

          <tbody>
            <tr>
              <td>`acceptTokenTypes`</td>
              <td>Allowlist of `token_type` values to accept from the token endpoint beyond `Bearer` and `DPoP`. Matched case-insensitively.</td>
              <td>string\[]</td>
              <td>No</td>
            </tr>

            <tr>
              <td>`accessToken`</td>
              <td>Expression locating the access token in the token endpoint response. Takes precedence over the standard `access_token` field when it resolves to a non-empty string.</td>
              <td>string</td>
              <td>No</td>
            </tr>

            <tr>
              <td>`refreshToken`</td>
              <td>Expression locating the refresh token in the token endpoint response. Takes precedence over the standard `refresh_token` field when it resolves to a non-empty string.</td>
              <td>string</td>
              <td>No</td>
            </tr>
          </tbody>
        </table>
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

<Accordion title="OAuth authorization flow">
  When the `authorization` type is `oauth2`, the runtime runs the authorization-code flow:

  1. The end-user clicks Connect in the StackOne Hub.
  2. The runtime builds the authorization URL from `authorizationUrl` and `authorizationParams`.
  3. The end-user signs in at the provider and grants access.
  4. The provider redirects back to the callback URL with an authorization code.
  5. The runtime exchanges that code for tokens at `tokenUrl`.
  6. The tokens are stored as the Linked Account's credentials.
</Accordion>

**Examples**

<Tabs>
  <Tab title="none">
    ```yaml theme={null}
    authorization:
      type: none
    ```
  </Tab>

  <Tab title="basic">
    ```yaml theme={null}
    authorization:
      type: basic
      username: $.credentials.username
      password: $.credentials.password
    ```
  </Tab>

  <Tab title="bearer">
    ```yaml theme={null}
    authorization:
      type: bearer
      token: $.credentials.accessToken
    ```
  </Tab>

  <Tab title="oauth2">
    ```yaml theme={null}
    authorization:
      type: oauth2
      authorizationUrl: https://auth.provider.com/oauth2/authorize
      authorizationParams:
        response_type: code
        client_id: $.credentials.clientId
        redirect_uri: ${apiHostUri}/connect/oauth2/{provider}/callback
        scope: $.credentials.scopes
      tokenUrl: https://auth.provider.com/oauth2/token
      token: $.credentials.accessToken
      includeBearer: true
    ```
  </Tab>
</Tabs>

## authorizationFlow

MCP OAuth authorization flow; static credentials are used when omitted.

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`clientRegistration`</td>
      <td>Client registration mechanism used with the MCP server.<br />Allowed: `cimd`, `dcr`<br />Default: `cimd`</td>
      <td>enum</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`discovery`</td>
      <td>Whether OAuth authorization-server metadata is discovered automatically.<br />Default: `true`</td>
      <td>boolean</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`scopes`</td>
      <td>OAuth scopes requested during the MCP authorization flow.</td>
      <td>string\[]</td>
      <td>No</td>
    </tr>

    <tr>
      <td>`serverUrl`</td>
      <td>MCP server URL the connect flow authorizes against.</td>
      <td>string</td>
      <td>No</td>
    </tr>
  </tbody>
</table>

**Examples**

```yaml theme={null}
authorizationFlow:
  clientRegistration: dcr
  scopes: [read, write]
```

## certificates

Mutual-TLS certificates and keys for this method.

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`certs`</td>
      <td>Client certificates used for mutual-TLS.</td>
      <td>string\[]</td>
      <td>No</td>
    </tr>

    <tr>
      <td>`keys`</td>
      <td>Private keys used for mutual-TLS.</td>
      <td>string\[]</td>
      <td>No</td>
    </tr>
  </tbody>
</table>

**Examples**

```yaml theme={null}
configFields:
  - key: client_cert
    label: Client certificate (PEM)
    type: password
    required: true
    secret: true
  - key: client_key
    label: Client private key (PEM)
    type: password
    required: true
    secret: true

certificates:
  certs: [client_cert]
  keys: [client_key]
```

## configFields

Credentials the end-user enters when linking an account.

<Tabs>
  <Tab title="text | password | text_area">
    <table>
      <colgroup>
        <col width="210" />

        <col width="400" />

        <col width="90" />

        <col width="90" />
      </colgroup>

      <thead>
        <tr>
          <th>Field</th>
          <th>Description</th>
          <th>Type</th>
          <th>Required</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>`computed`</td>
          <td>Field value is a JEXL expression in `value`, evaluated at runtime rather than entered by the user.</td>
          <td>boolean</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`description`</td>
          <td>Helper text explaining what the user should enter.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`externalSystemAccountIdentifier`</td>
          <td>Value identifies the account in the external system, used to match incoming webhook events to a linked account.</td>
          <td>boolean</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`key`</td>
          <td>Identifier the credential value is stored and referenced under.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`label`</td>
          <td>Human-readable name shown for this field.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`placeholder`</td>
          <td>Example value shown in the empty input to hint the expected format.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`readOnly`</td>
          <td>Whether the field is displayed but cannot be edited by the user.<br />Default: `false`</td>
          <td>boolean</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`required`</td>
          <td>Whether the field must have a value.<br />Default: `false`</td>
          <td>boolean</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`secret`</td>
          <td>Encrypt the value at rest and mask it in the UI.<br />Default: `false`</td>
          <td>boolean</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`tooltip`</td>
          <td>Additional guidance shown on hover for this field.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`type`</td>
          <td>Input control rendered for this credential field.<br />Allowed: `text`, `password`, `text_area`</td>
          <td>enum</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>[`validation`](#configfields-text-password-text-area-validation)</td>
          <td>Client-side validation constraint applied to the entered value.</td>
          <td>object</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`value`</td>
          <td>Preset or computed value for the field, such as a fixed default or a JEXL expression.</td>
          <td>string</td>
          <td>No</td>
        </tr>
      </tbody>
    </table>

    <AccordionGroup>
      <Accordion title="configFields.text | password | text_area.validation">
        Client-side validation constraint applied to the entered value.

        <table>
          <colgroup>
            <col width="210" />

            <col width="400" />

            <col width="90" />

            <col width="90" />
          </colgroup>

          <thead>
            <tr>
              <th>Field</th>
              <th>Description</th>
              <th>Type</th>
              <th>Required</th>
            </tr>
          </thead>

          <tbody>
            <tr>
              <td>`errorMessage`</td>
              <td>Message shown when the value fails the pattern or format check.</td>
              <td>string</td>
              <td>No</td>
            </tr>

            <tr>
              <td>`format`</td>
              <td>Named format the entered value must match, standing in for a common regular expression. Provide this or `pattern`, not both.<br />Allowed: `email`, `url`, `uri`, `uuid`, `date`, `datetime`</td>
              <td>enum</td>
              <td>No</td>
            </tr>

            <tr>
              <td>`pattern`</td>
              <td>Regular expression the entered value must match. Provide this or `format`, not both.</td>
              <td>string</td>
              <td>No</td>
            </tr>
          </tbody>
        </table>
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="select">
    <table>
      <colgroup>
        <col width="210" />

        <col width="400" />

        <col width="90" />

        <col width="90" />
      </colgroup>

      <thead>
        <tr>
          <th>Field</th>
          <th>Description</th>
          <th>Type</th>
          <th>Required</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>`computed`</td>
          <td>Field value is a JEXL expression in `value`, evaluated at runtime rather than entered by the user.</td>
          <td>boolean</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`description`</td>
          <td>Helper text explaining what the user should enter.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`externalSystemAccountIdentifier`</td>
          <td>Value identifies the account in the external system, used to match incoming webhook events to a linked account.</td>
          <td>boolean</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`key`</td>
          <td>Identifier the credential value is stored and referenced under.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`label`</td>
          <td>Human-readable name shown for this field.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>[`options`](#configfields-select-options)</td>
          <td>Selectable choices offered for this field.</td>
          <td>object\[]</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`placeholder`</td>
          <td>Example value shown in the empty input to hint the expected format.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`readOnly`</td>
          <td>Whether the field is displayed but cannot be edited by the user.<br />Default: `false`</td>
          <td>boolean</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`required`</td>
          <td>Whether the field must have a value.<br />Default: `false`</td>
          <td>boolean</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`secret`</td>
          <td>Encrypt the value at rest and mask it in the UI.<br />Default: `false`</td>
          <td>boolean</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`tooltip`</td>
          <td>Additional guidance shown on hover for this field.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`type`</td>
          <td>Input control rendered for this credential field.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`value`</td>
          <td>Preset or computed value for the field, such as a fixed default or a JEXL expression.</td>
          <td>string</td>
          <td>No</td>
        </tr>
      </tbody>
    </table>

    <AccordionGroup>
      <Accordion title="configFields.select.options">
        Selectable choices offered for this field.

        <table>
          <colgroup>
            <col width="210" />

            <col width="400" />

            <col width="90" />

            <col width="90" />
          </colgroup>

          <thead>
            <tr>
              <th>Field</th>
              <th>Description</th>
              <th>Type</th>
              <th>Required</th>
            </tr>
          </thead>

          <tbody>
            <tr>
              <td>`label`</td>
              <td>Human-readable text shown for this option.</td>
              <td>string</td>
              <td>Yes</td>
            </tr>

            <tr>
              <td>`value`</td>
              <td>Value stored when this option is selected.</td>
              <td>string</td>
              <td>Yes</td>
            </tr>
          </tbody>
        </table>
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

**Examples**

```yaml theme={null}
configFields:
  - key: subdomain
    label: Subdomain
    type: text
    required: true
    placeholder: acme-corp
  - key: client_id
    label: Client ID
    type: text
    required: true
  - key: client_secret
    label: Client Secret
    type: password
    required: true
    secret: true
  - key: region
    label: Region
    type: select
    required: true
    options:
      - { value: us, label: United States }
      - { value: eu, label: European Union }
```

## configNotices

Callouts shown while entering config fields.

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`anchor`</td>
      <td>Field key the notice is shown above. Only valid when position is top.</td>
      <td>string</td>
      <td>No</td>
    </tr>

    <tr>
      <td>`description`</td>
      <td>Text shown in the notice.</td>
      <td>string</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`key`</td>
      <td>Identifier for the notice.</td>
      <td>string</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`position`</td>
      <td>Whether the notice appears above or below the fields.<br />Allowed: `top`, `bottom`<br />Default: `top`</td>
      <td>enum</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`type`</td>
      <td>Visual style of the notice.<br />Allowed: `warning`, `info`<br />Default: `info`</td>
      <td>enum</td>
      <td>Yes</td>
    </tr>
  </tbody>
</table>

**Examples**

```yaml theme={null}
configNotices:
  - key: sandbox_warning
    type: warning
    description: Use your sandbox credentials while testing.
    position: top
    anchor: client_id
```

## environments

Deployment targets selectable for this method.

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`key`</td>
      <td>Identifier stored for the selected environment.</td>
      <td>string</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`name`</td>
      <td>Human-readable environment name.</td>
      <td>string</td>
      <td>Yes</td>
    </tr>
  </tbody>
</table>

**Examples**

```yaml theme={null}
environments:
  - key: production
    name: Production
  - key: sandbox
    name: Sandbox
```

## refreshAuthentication

Configuration for refreshing expired credentials.

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>[`action`](#refreshauthentication-action)</td>
      <td>Action executed to refresh the credentials.</td>
      <td>object</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`schedule`</td>
      <td>Cron expression for proactively refreshing credentials.</td>
      <td>string</td>
      <td>No</td>
    </tr>
  </tbody>
</table>

<AccordionGroup>
  <Accordion title="refreshAuthentication.action">
    Action executed to refresh the credentials.

    Same fields as [actions](/connector-yaml-reference/yaml-schema/actions).
  </Accordion>
</AccordionGroup>

<Accordion title="Token refresh mechanics">
  The initial OAuth exchange stores the provider's refresh token in the Linked Account's credentials. `refreshAuthentication` then keeps the access token current:

  1. On the `schedule` cron, the runtime runs the `refresh_token` action.
  2. The action sends the stored refresh token to the provider's token endpoint.
  3. The provider returns a new access token, and sometimes a new refresh token.
  4. The returned tokens replace the Linked Account's credentials.

  Set `schedule` to fire before the access token expires, so requests never use a stale token.
</Accordion>

**Examples**

```yaml theme={null}
refreshAuthentication:
  schedule: '*/50 * * * *'   # every 50 minutes (10 min before 60 min token expiry)
  action:
    actionId: refresh_oauth_token
    actionType: refresh_token
    label: Refresh OAuth token
    description: Exchange refresh_token for a new access_token.
    steps:
      - stepId: refresh
        description: POST to the token endpoint.
        stepFunction:
          functionName: request
          version: v1
          parameters:
            url: https://auth.provider.com/oauth/token
            method: post
            args:
              - { name: grant_type, value: refresh_token, in: body }
              - { name: refresh_token, value: '${credentials.refresh_token}', in: body }
              - { name: client_id, value: '${credentials.client_id}', in: body }
              - { name: client_secret, value: '${credentials.client_secret}', in: body }
```

## setupFields

Credentials entered when creating a Connector Profile.

<Tabs>
  <Tab title="text | password | text_area">
    <table>
      <colgroup>
        <col width="210" />

        <col width="400" />

        <col width="90" />

        <col width="90" />
      </colgroup>

      <thead>
        <tr>
          <th>Field</th>
          <th>Description</th>
          <th>Type</th>
          <th>Required</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>`computed`</td>
          <td>Field value is a JEXL expression in `value`, evaluated at runtime rather than entered by the user.</td>
          <td>boolean</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`description`</td>
          <td>Helper text explaining what the user should enter.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`externalSystemAccountIdentifier`</td>
          <td>Value identifies the account in the external system, used to match incoming webhook events to a linked account.</td>
          <td>boolean</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`key`</td>
          <td>Identifier the credential value is stored and referenced under.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`label`</td>
          <td>Human-readable name shown for this field.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`placeholder`</td>
          <td>Example value shown in the empty input to hint the expected format.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`readOnly`</td>
          <td>Whether the field is displayed but cannot be edited by the user.<br />Default: `false`</td>
          <td>boolean</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`required`</td>
          <td>Whether the field must have a value.<br />Default: `false`</td>
          <td>boolean</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`secret`</td>
          <td>Encrypt the value at rest and mask it in the UI.<br />Default: `false`</td>
          <td>boolean</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`tooltip`</td>
          <td>Additional guidance shown on hover for this field.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`type`</td>
          <td>Input control rendered for this credential field.<br />Allowed: `text`, `password`, `text_area`</td>
          <td>enum</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>[`validation`](#setupfields-text-password-text-area-validation)</td>
          <td>Client-side validation constraint applied to the entered value.</td>
          <td>object</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`value`</td>
          <td>Preset or computed value for the field, such as a fixed default or a JEXL expression.</td>
          <td>string</td>
          <td>No</td>
        </tr>
      </tbody>
    </table>

    <AccordionGroup>
      <Accordion title="setupFields.text | password | text_area.validation">
        Client-side validation constraint applied to the entered value.

        <table>
          <colgroup>
            <col width="210" />

            <col width="400" />

            <col width="90" />

            <col width="90" />
          </colgroup>

          <thead>
            <tr>
              <th>Field</th>
              <th>Description</th>
              <th>Type</th>
              <th>Required</th>
            </tr>
          </thead>

          <tbody>
            <tr>
              <td>`errorMessage`</td>
              <td>Message shown when the value fails the pattern or format check.</td>
              <td>string</td>
              <td>No</td>
            </tr>

            <tr>
              <td>`format`</td>
              <td>Named format the entered value must match, standing in for a common regular expression. Provide this or `pattern`, not both.<br />Allowed: `email`, `url`, `uri`, `uuid`, `date`, `datetime`</td>
              <td>enum</td>
              <td>No</td>
            </tr>

            <tr>
              <td>`pattern`</td>
              <td>Regular expression the entered value must match. Provide this or `format`, not both.</td>
              <td>string</td>
              <td>No</td>
            </tr>
          </tbody>
        </table>
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="select">
    <table>
      <colgroup>
        <col width="210" />

        <col width="400" />

        <col width="90" />

        <col width="90" />
      </colgroup>

      <thead>
        <tr>
          <th>Field</th>
          <th>Description</th>
          <th>Type</th>
          <th>Required</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>`computed`</td>
          <td>Field value is a JEXL expression in `value`, evaluated at runtime rather than entered by the user.</td>
          <td>boolean</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`description`</td>
          <td>Helper text explaining what the user should enter.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`externalSystemAccountIdentifier`</td>
          <td>Value identifies the account in the external system, used to match incoming webhook events to a linked account.</td>
          <td>boolean</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`key`</td>
          <td>Identifier the credential value is stored and referenced under.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`label`</td>
          <td>Human-readable name shown for this field.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>[`options`](#setupfields-select-options)</td>
          <td>Selectable choices offered for this field.</td>
          <td>object\[]</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`placeholder`</td>
          <td>Example value shown in the empty input to hint the expected format.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`readOnly`</td>
          <td>Whether the field is displayed but cannot be edited by the user.<br />Default: `false`</td>
          <td>boolean</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`required`</td>
          <td>Whether the field must have a value.<br />Default: `false`</td>
          <td>boolean</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`secret`</td>
          <td>Encrypt the value at rest and mask it in the UI.<br />Default: `false`</td>
          <td>boolean</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`tooltip`</td>
          <td>Additional guidance shown on hover for this field.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`type`</td>
          <td>Input control rendered for this credential field.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`value`</td>
          <td>Preset or computed value for the field, such as a fixed default or a JEXL expression.</td>
          <td>string</td>
          <td>No</td>
        </tr>
      </tbody>
    </table>

    <AccordionGroup>
      <Accordion title="setupFields.select.options">
        Selectable choices offered for this field.

        <table>
          <colgroup>
            <col width="210" />

            <col width="400" />

            <col width="90" />

            <col width="90" />
          </colgroup>

          <thead>
            <tr>
              <th>Field</th>
              <th>Description</th>
              <th>Type</th>
              <th>Required</th>
            </tr>
          </thead>

          <tbody>
            <tr>
              <td>`label`</td>
              <td>Human-readable text shown for this option.</td>
              <td>string</td>
              <td>Yes</td>
            </tr>

            <tr>
              <td>`value`</td>
              <td>Value stored when this option is selected.</td>
              <td>string</td>
              <td>Yes</td>
            </tr>
          </tbody>
        </table>
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

**Examples**

```yaml theme={null}
setupFields:
  - key: oauth_client_id
    label: OAuth Client ID
    type: text
    required: true
  - key: oauth_client_secret
    label: OAuth Client Secret
    type: password
    required: true
    secret: true
```

## setupNotices

Callouts shown while entering setup fields.

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`anchor`</td>
      <td>Field key the notice is shown above. Only valid when position is top.</td>
      <td>string</td>
      <td>No</td>
    </tr>

    <tr>
      <td>`description`</td>
      <td>Text shown in the notice.</td>
      <td>string</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`key`</td>
      <td>Identifier for the notice.</td>
      <td>string</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`position`</td>
      <td>Whether the notice appears above or below the fields.<br />Allowed: `top`, `bottom`<br />Default: `top`</td>
      <td>enum</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`type`</td>
      <td>Visual style of the notice.<br />Allowed: `warning`, `info`<br />Default: `info`</td>
      <td>enum</td>
      <td>Yes</td>
    </tr>
  </tbody>
</table>

**Examples**

```yaml theme={null}
setupNotices:
  - key: rotation_reminder
    type: info
    description: Rotate the client secret every 90 days.
    position: bottom
```

## support

Help resources shown while connecting with this method.

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`description`</td>
      <td>Help text guiding the user through connecting.</td>
      <td>string</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`guides`](#support-guides)</td>
      <td>Step-by-step connection guides.</td>
      <td>object</td>
      <td>No</td>
    </tr>

    <tr>
      <td>`link`</td>
      <td>URL to external setup documentation. Defaults to the generated connector guide on docs.stackone.com when omitted.</td>
      <td>string</td>
      <td>No</td>
    </tr>
  </tbody>
</table>

<AccordionGroup>
  <Accordion title="support.guides">
    Step-by-step connection guides.

    <table>
      <colgroup>
        <col width="210" />

        <col width="400" />

        <col width="90" />

        <col width="90" />
      </colgroup>

      <thead>
        <tr>
          <th>Field</th>
          <th>Description</th>
          <th>Type</th>
          <th>Required</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>[`config`](#support-guides-config)</td>
          <td>Guide for the credentials end-users enter per connection.</td>
          <td>object</td>
          <td>No</td>
        </tr>

        <tr>
          <td>[`setup`](#support-guides-setup)</td>
          <td>Guide for the credentials your team registers once.</td>
          <td>object</td>
          <td>No</td>
        </tr>
      </tbody>
    </table>

    <AccordionGroup>
      <Accordion title="support.guides.config">
        Guide for the credentials end-users enter per connection.

        <table>
          <colgroup>
            <col width="210" />

            <col width="400" />

            <col width="90" />

            <col width="90" />
          </colgroup>

          <thead>
            <tr>
              <th>Field</th>
              <th>Description</th>
              <th>Type</th>
              <th>Required</th>
            </tr>
          </thead>

          <tbody>
            <tr>
              <td>[`sections`](#support-guides-config-sections)</td>
              <td>Ordered sections making up the guide.</td>
              <td>object\[]</td>
              <td>Yes</td>
            </tr>

            <tr>
              <td>`warning`</td>
              <td>Cautionary note shown at the top of the guide.</td>
              <td>string</td>
              <td>No</td>
            </tr>
          </tbody>
        </table>

        <AccordionGroup>
          <Accordion title="support.guides.config.sections">
            Ordered sections making up the guide.

            <table>
              <colgroup>
                <col width="210" />

                <col width="400" />

                <col width="90" />

                <col width="90" />
              </colgroup>

              <thead>
                <tr>
                  <th>Field</th>
                  <th>Description</th>
                  <th>Type</th>
                  <th>Required</th>
                </tr>
              </thead>

              <tbody>
                <tr>
                  <td>`applicableScopes`</td>
                  <td>Scope names for which this section is shown. Space-separated, with any name that contains spaces wrapped in double quotes.</td>
                  <td>string</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>`content`</td>
                  <td>Introductory text for the section.</td>
                  <td>string</td>
                  <td>Yes</td>
                </tr>

                <tr>
                  <td>[`image`](#support-guides-config-sections-image)</td>
                  <td>Illustrative image for the section.</td>
                  <td>object</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>`list`</td>
                  <td>Ordered items elaborating the section.</td>
                  <td>string\[]</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>[`steps`](#support-guides-config-sections-steps)</td>
                  <td>Ordered steps making up the section.</td>
                  <td>object\[]</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>`title`</td>
                  <td>Heading for this guide section.</td>
                  <td>string</td>
                  <td>Yes</td>
                </tr>
              </tbody>
            </table>

            <AccordionGroup>
              <Accordion title="support.guides.config.sections.image">
                Illustrative image for the section.

                <table>
                  <colgroup>
                    <col width="210" />

                    <col width="400" />

                    <col width="90" />

                    <col width="90" />
                  </colgroup>

                  <thead>
                    <tr>
                      <th>Field</th>
                      <th>Description</th>
                      <th>Type</th>
                      <th>Required</th>
                    </tr>
                  </thead>

                  <tbody>
                    <tr>
                      <td>`alt`</td>
                      <td>Alternative text describing the image.</td>
                      <td>string</td>
                      <td>Yes</td>
                    </tr>

                    <tr>
                      <td>`src`</td>
                      <td>Image URL or a path relative to the connector.</td>
                      <td>string</td>
                      <td>Yes</td>
                    </tr>
                  </tbody>
                </table>
              </Accordion>

              <Accordion title="support.guides.config.sections.steps">
                Ordered steps making up the section.

                <table>
                  <colgroup>
                    <col width="210" />

                    <col width="400" />

                    <col width="90" />

                    <col width="90" />
                  </colgroup>

                  <thead>
                    <tr>
                      <th>Field</th>
                      <th>Description</th>
                      <th>Type</th>
                      <th>Required</th>
                    </tr>
                  </thead>

                  <tbody>
                    <tr>
                      <td>`applicableScopes`</td>
                      <td>Scope names for which this step is shown. Space-separated, with any name that contains spaces wrapped in double quotes.</td>
                      <td>string</td>
                      <td>No</td>
                    </tr>

                    <tr>
                      <td>`content`</td>
                      <td>Body text describing what the user should do.</td>
                      <td>string</td>
                      <td>Yes</td>
                    </tr>

                    <tr>
                      <td>`displayScopes`</td>
                      <td>Whether the step shows badges for the actions its scopes unlock.</td>
                      <td>boolean</td>
                      <td>No</td>
                    </tr>

                    <tr>
                      <td>[`image`](#support-guides-config-sections-steps-image)</td>
                      <td>Illustrative image for the step.</td>
                      <td>object</td>
                      <td>No</td>
                    </tr>

                    <tr>
                      <td>`list`</td>
                      <td>Ordered items elaborating the step.</td>
                      <td>string\[]</td>
                      <td>No</td>
                    </tr>

                    <tr>
                      <td>`title`</td>
                      <td>Heading for this guide step.</td>
                      <td>string</td>
                      <td>Yes</td>
                    </tr>
                  </tbody>
                </table>

                <AccordionGroup>
                  <Accordion title="support.guides.config.sections.steps.image">
                    Illustrative image for the step.

                    <table>
                      <colgroup>
                        <col width="210" />

                        <col width="400" />

                        <col width="90" />

                        <col width="90" />
                      </colgroup>

                      <thead>
                        <tr>
                          <th>Field</th>
                          <th>Description</th>
                          <th>Type</th>
                          <th>Required</th>
                        </tr>
                      </thead>

                      <tbody>
                        <tr>
                          <td>`alt`</td>
                          <td>Alternative text describing the image.</td>
                          <td>string</td>
                          <td>Yes</td>
                        </tr>

                        <tr>
                          <td>`src`</td>
                          <td>Image URL or a path relative to the connector.</td>
                          <td>string</td>
                          <td>Yes</td>
                        </tr>
                      </tbody>
                    </table>
                  </Accordion>
                </AccordionGroup>
              </Accordion>
            </AccordionGroup>
          </Accordion>
        </AccordionGroup>
      </Accordion>

      <Accordion title="support.guides.setup">
        Guide for the credentials your team registers once.

        <table>
          <colgroup>
            <col width="210" />

            <col width="400" />

            <col width="90" />

            <col width="90" />
          </colgroup>

          <thead>
            <tr>
              <th>Field</th>
              <th>Description</th>
              <th>Type</th>
              <th>Required</th>
            </tr>
          </thead>

          <tbody>
            <tr>
              <td>[`sections`](#support-guides-setup-sections)</td>
              <td>Ordered sections making up the guide.</td>
              <td>object\[]</td>
              <td>Yes</td>
            </tr>

            <tr>
              <td>`warning`</td>
              <td>Cautionary note shown at the top of the guide.</td>
              <td>string</td>
              <td>No</td>
            </tr>
          </tbody>
        </table>

        <AccordionGroup>
          <Accordion title="support.guides.setup.sections">
            Ordered sections making up the guide.

            <table>
              <colgroup>
                <col width="210" />

                <col width="400" />

                <col width="90" />

                <col width="90" />
              </colgroup>

              <thead>
                <tr>
                  <th>Field</th>
                  <th>Description</th>
                  <th>Type</th>
                  <th>Required</th>
                </tr>
              </thead>

              <tbody>
                <tr>
                  <td>`applicableScopes`</td>
                  <td>Scope names for which this section is shown. Space-separated, with any name that contains spaces wrapped in double quotes.</td>
                  <td>string</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>`content`</td>
                  <td>Introductory text for the section.</td>
                  <td>string</td>
                  <td>Yes</td>
                </tr>

                <tr>
                  <td>[`image`](#support-guides-setup-sections-image)</td>
                  <td>Illustrative image for the section.</td>
                  <td>object</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>`list`</td>
                  <td>Ordered items elaborating the section.</td>
                  <td>string\[]</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>[`steps`](#support-guides-setup-sections-steps)</td>
                  <td>Ordered steps making up the section.</td>
                  <td>object\[]</td>
                  <td>No</td>
                </tr>

                <tr>
                  <td>`title`</td>
                  <td>Heading for this guide section.</td>
                  <td>string</td>
                  <td>Yes</td>
                </tr>
              </tbody>
            </table>

            <AccordionGroup>
              <Accordion title="support.guides.setup.sections.image">
                Illustrative image for the section.

                <table>
                  <colgroup>
                    <col width="210" />

                    <col width="400" />

                    <col width="90" />

                    <col width="90" />
                  </colgroup>

                  <thead>
                    <tr>
                      <th>Field</th>
                      <th>Description</th>
                      <th>Type</th>
                      <th>Required</th>
                    </tr>
                  </thead>

                  <tbody>
                    <tr>
                      <td>`alt`</td>
                      <td>Alternative text describing the image.</td>
                      <td>string</td>
                      <td>Yes</td>
                    </tr>

                    <tr>
                      <td>`src`</td>
                      <td>Image URL or a path relative to the connector.</td>
                      <td>string</td>
                      <td>Yes</td>
                    </tr>
                  </tbody>
                </table>
              </Accordion>

              <Accordion title="support.guides.setup.sections.steps">
                Ordered steps making up the section.

                <table>
                  <colgroup>
                    <col width="210" />

                    <col width="400" />

                    <col width="90" />

                    <col width="90" />
                  </colgroup>

                  <thead>
                    <tr>
                      <th>Field</th>
                      <th>Description</th>
                      <th>Type</th>
                      <th>Required</th>
                    </tr>
                  </thead>

                  <tbody>
                    <tr>
                      <td>`applicableScopes`</td>
                      <td>Scope names for which this step is shown. Space-separated, with any name that contains spaces wrapped in double quotes.</td>
                      <td>string</td>
                      <td>No</td>
                    </tr>

                    <tr>
                      <td>`content`</td>
                      <td>Body text describing what the user should do.</td>
                      <td>string</td>
                      <td>Yes</td>
                    </tr>

                    <tr>
                      <td>`displayScopes`</td>
                      <td>Whether the step shows badges for the actions its scopes unlock.</td>
                      <td>boolean</td>
                      <td>No</td>
                    </tr>

                    <tr>
                      <td>[`image`](#support-guides-setup-sections-steps-image)</td>
                      <td>Illustrative image for the step.</td>
                      <td>object</td>
                      <td>No</td>
                    </tr>

                    <tr>
                      <td>`list`</td>
                      <td>Ordered items elaborating the step.</td>
                      <td>string\[]</td>
                      <td>No</td>
                    </tr>

                    <tr>
                      <td>`title`</td>
                      <td>Heading for this guide step.</td>
                      <td>string</td>
                      <td>Yes</td>
                    </tr>
                  </tbody>
                </table>

                <AccordionGroup>
                  <Accordion title="support.guides.setup.sections.steps.image">
                    Illustrative image for the step.

                    <table>
                      <colgroup>
                        <col width="210" />

                        <col width="400" />

                        <col width="90" />

                        <col width="90" />
                      </colgroup>

                      <thead>
                        <tr>
                          <th>Field</th>
                          <th>Description</th>
                          <th>Type</th>
                          <th>Required</th>
                        </tr>
                      </thead>

                      <tbody>
                        <tr>
                          <td>`alt`</td>
                          <td>Alternative text describing the image.</td>
                          <td>string</td>
                          <td>Yes</td>
                        </tr>

                        <tr>
                          <td>`src`</td>
                          <td>Image URL or a path relative to the connector.</td>
                          <td>string</td>
                          <td>Yes</td>
                        </tr>
                      </tbody>
                    </table>
                  </Accordion>
                </AccordionGroup>
              </Accordion>
            </AccordionGroup>
          </Accordion>
        </AccordionGroup>
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>

**Examples**

```yaml theme={null}
support:
  link: https://docs.provider.com/oauth-setup
  description: How to register an OAuth app in the provider dashboard.
  guides:
    setup:
      sections:
        - title: Register an OAuth app
          content: Sign in to the provider dashboard and create an app.
          steps:
            - title: Open the Developer settings
              content: Click your avatar, then Developer settings.
              image: { src: /images/connectors/provider/dev-settings.png, alt: Developer settings menu }
            - title: Create a new OAuth app
              content: Set the redirect URL to the value shown in the Hub.
```

## testActions

Actions run to validate a connection after authentication.

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>[`action`](#testactions-action)</td>
      <td>Action id or definition executed to test the connection.</td>
      <td>union</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`condition`</td>
      <td>JEXL expression gating whether the test action runs.</td>
      <td>string</td>
      <td>No</td>
    </tr>

    <tr>
      <td>`required`</td>
      <td>Currently not in use.<br />Default: `true`</td>
      <td>boolean</td>
      <td>Yes</td>
    </tr>
  </tbody>
</table>

<AccordionGroup>
  <Accordion title="testActions.action">
    Action id or definition executed to test the connection.

    <Tabs>
      <Tab title="string">
        A `string` value.
      </Tab>

      <Tab title="actions">
        Same fields as [actions](/connector-yaml-reference/yaml-schema/actions).
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

**Examples**

```yaml theme={null}
testActions:
  - action: get_current_user
    required: true
  - action: list_admin_settings
    condition: '${credentials.scope.contains("admin")}'
    required: false
```

## Related

<CardGroup cols={2}>
  <Card title="scopeDefinitions" icon="gear" href="/connector-yaml-reference/yaml-schema/overview#scopedefinitions">
    Declare available scopes; profiles can pin requiredScopes.
  </Card>

  <Card title="baseUrl" icon="gear" href="/connector-yaml-reference/yaml-schema/overview#baseurl">
    Typically interpolates a \${credentials.subdomain} here.
  </Card>

  <Card title="documentation" icon="gear" href="/connector-yaml-reference/yaml-schema/overview#documentation">
    Connector-level external doc links, separate from per-auth guides.
  </Card>

  <Card title="Actions overview" icon="book" href="/connector-yaml-reference/yaml-schema/actions#overview">
    Actions referenced by testActions and refresh\_token must exist in actions\[].
  </Card>
</CardGroup>