Authentication

Field reference for a connector’s authentication types.

Structure

Multiple authentication methods per connector are allowed.

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.

Field	Description	Type	Required
authorization	Runtime authorization strategy applied to outgoing requests.	union	Yes
certificates	Mutual-TLS certificates and keys for this method.	object	No
configFields	Credentials the end-user enters when linking an account.	array	No
configNotices	Callouts shown while entering config fields.	object[]	No
environments	Deployment targets selectable for this method.	object[]	Yes
grantType	OAuth grant flow used to obtain tokens. Allowed: authorization_code, client_credentials Default: authorization_code	enum	No
label	Display name for this authentication method.	string	Yes
refreshAuthentication	Configuration for refreshing expired credentials.	object	No
releaseStage	Maturity level of this authentication method. Defaults to the highest stage among the actions and events it can run. Allowed: preview, beta, ga, deprecated, internal	enum	No
requiredScopes	Scope names required by this authentication method. Space-separated, with any name that contains spaces wrapped in double quotes.	string	No
setupFields	Credentials entered when creating a Connector Profile.	array	No
setupNotices	Callouts shown while entering setup fields.	object[]	No
support	Help resources shown while connecting with this method.	object	No
testActions	Actions run to validate a connection after authentication.	object[]	No
type	Selects the OAuth 2.0 authentication method.	string	Yes
authorizationFlow	MCP OAuth authorization flow; static credentials are used when omitted.	object	No

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

oauth2

The grantType field selects the OAuth grant flow, either authorization_code (default) or client_credentials.

authentication:
  - oauth2:
      type: oauth2
      label: OAuth 2.0
      grantType: authorization_code
      authorization: { ... }
      environments: [ ... ]
      # ...remaining fields

custom

The general-purpose method, for providers whose authentication doesn’t fit oauth2, oidc, or mcp.

authentication:
  - api_key:
      type: custom
      label: API Key
      authorization: { ... }
      environments: [ ... ]
      # ...remaining fields

oidc

Runs the authorization-code flow using standard OpenID Connect discovery.

authentication:
  - oidc:
      type: oidc
      label: OpenID Connect
      authorization: { ... }
      environments: [ ... ]
      # ...remaining fields

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.

authentication:
  - mcp:
      type: mcp
      label: MCP Server
      authorizationFlow:
        clientRegistration: dcr
        scopes: [read, write]
      authorization: { ... }
      environments: [ ... ]
      # ...remaining fields

authorization

Runtime authorization strategy applied to outgoing requests.

none

Field	Description	Type	Required
redirectUri	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
signing	Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.	union	No
type	Sends requests without an authorization header.	string	Yes

authorization.none.signing

Optional request signing applied to outgoing requests. Selects AWS SigV4 or HMAC signing.

aws4

Field	Description	Type	Required
region	AWS region used in the signing credential scope. Falls back to the credential region or us-east-1 when omitted.	string	No
service	AWS service name used in the signing credential scope. For example s3 or execute-api.	string	Yes
strategy	Signs requests with AWS Signature Version 4.	string	Yes

hmac

Field	Description	Type	Required
algorithm	Hash algorithm for the HMAC signature. Defaults to sha256. Allowed: sha1, sha256, sha512	enum	No
dateFormat	Timestamp format used in the signed string. Either iso8601 (default) or rfc2822. Allowed: iso8601, rfc2822	enum	No
headerName	Header the signature is written into. Defaults to X-Signature.	string	No
includeBodyHash	Hash the request body into the signed string, defaulting to true. When false, form-urlencoded body params are folded into the canonical string instead.	boolean	No
includeHost	Include the request hostname in the signed canonical string. Defaults to false.	boolean	No
outputFormat	Where the signature is emitted. header writes a signature header and basic writes an HTTP Basic Authorization header. Allowed: header, basic	enum	No
prefix	Prefix prepended to the signature value in the header. Defaults to hmac-<algorithm>.	string	No
strategy	Signs requests with an HMAC signature over a canonical request string.	string	Yes
username	Username paired with the signature when outputFormat is basic.	string	No

basic

Field	Description	Type	Required
encoding	Encoding applied to the username:password pair. Defaults to base64.	string	No
password	Password for HTTP Basic authentication.	string	No
redirectUri	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
type	Configures HTTP Basic authentication.	string	Yes
username	Username for HTTP Basic authentication.	string	No

bearer

Field	Description	Type	Required
includeBearer	Prefix the token with Bearer in the Authorization header. Defaults to true. Default: true	boolean	Yes
redirectUri	OAuth callback URL carried as connect-time metadata. Not used when authorizing requests.	string	No
token	Token sent on each request. Supports expressions.	string	Yes
type	Configures bearer token authentication.	string	Yes

oauth2

Field	Description	Type	Required
additionalTokenFields	Extra credential fields to read from the token endpoint response. Each key is a credential name and each value an expression.	object	No
authorizationParams	Extra query parameters appended to the authorization URL. Values support expressions.	object	No
authorizationUrl	Provider authorization endpoint where the user grants access.	string	No
callbackParams	Maps OAuth callback query parameter names to the credential keys their values are stored under. Cannot target reserved credential keys.	object	No
customHeaders	Additional HTTP headers sent with token endpoint requests.	object	No
includeBearer	Prefix the token with Bearer in the Authorization header. Defaults to true. Default: true	boolean	Yes
issuer	OpenID Connect issuer identifier for the provider.	string	No
pkce	Enable PKCE for the authorization code flow.	boolean	No
redirectUri	Overrides the OAuth callback URL. The computed callback URL can be seen on the connector profile.	string	No
scopeDelimiter	Delimiter used to separate scopes when requesting authorization.	string	No
scopes	OAuth scopes requested during authorization.	string	No
token	Expression that resolves the access token sent on each request.	string	Yes
tokenExpiresIn	Access token lifetime in seconds.	number	No
tokenParams	Extra parameters sent to the token endpoint. Values support expressions.	object	No
tokenRefreshExpiresIn	Refresh token lifetime in seconds.	number	No
tokenResponse	Adjusts how a non-standard token endpoint response is parsed.	object	No
tokenUrl	Provider token endpoint used to exchange the authorization code and to refresh tokens.	string	No
type	Configures OAuth 2.0 authentication.	string	Yes

authorization.oauth2.tokenResponse

Adjusts how a non-standard token endpoint response is parsed.

Field	Description	Type	Required
acceptTokenTypes	Allowlist of token_type values to accept from the token endpoint beyond Bearer and DPoP. Matched case-insensitively.	string[]	No
accessToken	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.	string	No
refreshToken	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.	string	No

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.

Examples

none

authorization:
  type: none

basic

authorization:
  type: basic
  username: $.credentials.username
  password: $.credentials.password

bearer

authorization:
  type: bearer
  token: $.credentials.accessToken

oauth2

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

authorizationFlow

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

Field	Description	Type	Required
clientRegistration	Client registration mechanism used with the MCP server. Allowed: cimd, dcr Default: cimd	enum	Yes
discovery	Whether OAuth authorization-server metadata is discovered automatically. Default: true	boolean	Yes
scopes	OAuth scopes requested during the MCP authorization flow.	string[]	No
serverUrl	MCP server URL the connect flow authorizes against.	string	No

Examples

authorizationFlow:
  clientRegistration: dcr
  scopes: [read, write]

certificates

Mutual-TLS certificates and keys for this method.

Field	Description	Type	Required
certs	Client certificates used for mutual-TLS.	string[]	No
keys	Private keys used for mutual-TLS.	string[]	No

Examples

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.

text | password | text_area

Field	Description	Type	Required
computed	Field value is a JEXL expression in value, evaluated at runtime rather than entered by the user.	boolean	No
description	Helper text explaining what the user should enter.	string	No
externalSystemAccountIdentifier	Value identifies the account in the external system, used to match incoming webhook events to a linked account.	boolean	No
key	Identifier the credential value is stored and referenced under.	string	Yes
label	Human-readable name shown for this field.	string	Yes
placeholder	Example value shown in the empty input to hint the expected format.	string	No
readOnly	Whether the field is displayed but cannot be edited by the user. Default: false	boolean	Yes
required	Whether the field must have a value. Default: false	boolean	Yes
secret	Encrypt the value at rest and mask it in the UI. Default: false	boolean	Yes
tooltip	Additional guidance shown on hover for this field.	string	No
type	Input control rendered for this credential field. Allowed: text, password, text_area	enum	Yes
validation	Client-side validation constraint applied to the entered value.	object	No
value	Preset or computed value for the field, such as a fixed default or a JEXL expression.	string	No

configFields.text | password | text_area.validation

Client-side validation constraint applied to the entered value.

Field	Description	Type	Required
errorMessage	Message shown when the value fails the pattern or format check.	string	No
format	Named format the entered value must match, standing in for a common regular expression. Provide this or pattern, not both. Allowed: email, url, uri, uuid, date, datetime	enum	No
pattern	Regular expression the entered value must match. Provide this or format, not both.	string	No

select

Field	Description	Type	Required
computed	Field value is a JEXL expression in value, evaluated at runtime rather than entered by the user.	boolean	No
description	Helper text explaining what the user should enter.	string	No
externalSystemAccountIdentifier	Value identifies the account in the external system, used to match incoming webhook events to a linked account.	boolean	No
key	Identifier the credential value is stored and referenced under.	string	Yes
label	Human-readable name shown for this field.	string	Yes
options	Selectable choices offered for this field.	object[]	Yes
placeholder	Example value shown in the empty input to hint the expected format.	string	No
readOnly	Whether the field is displayed but cannot be edited by the user. Default: false	boolean	Yes
required	Whether the field must have a value. Default: false	boolean	Yes
secret	Encrypt the value at rest and mask it in the UI. Default: false	boolean	Yes
tooltip	Additional guidance shown on hover for this field.	string	No
type	Input control rendered for this credential field.	string	Yes
value	Preset or computed value for the field, such as a fixed default or a JEXL expression.	string	No

configFields.select.options

Selectable choices offered for this field.

Field	Description	Type	Required
label	Human-readable text shown for this option.	string	Yes
value	Value stored when this option is selected.	string	Yes

Examples

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.

Field	Description	Type	Required
anchor	Field key the notice is shown above. Only valid when position is top.	string	No
description	Text shown in the notice.	string	Yes
key	Identifier for the notice.	string	Yes
position	Whether the notice appears above or below the fields. Allowed: top, bottom Default: top	enum	Yes
type	Visual style of the notice. Allowed: warning, info Default: info	enum	Yes

Examples

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.

Field	Description	Type	Required
key	Identifier stored for the selected environment.	string	Yes
name	Human-readable environment name.	string	Yes

Examples

environments:
  - key: production
    name: Production
  - key: sandbox
    name: Sandbox

refreshAuthentication

Configuration for refreshing expired credentials.

Field	Description	Type	Required
action	Action executed to refresh the credentials.	object	Yes
schedule	Cron expression for proactively refreshing credentials.	string	No

refreshAuthentication.action

Action executed to refresh the credentials.

Same fields as actions.

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.

Examples

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.

text | password | text_area

Field	Description	Type	Required
computed	Field value is a JEXL expression in value, evaluated at runtime rather than entered by the user.	boolean	No
description	Helper text explaining what the user should enter.	string	No
externalSystemAccountIdentifier	Value identifies the account in the external system, used to match incoming webhook events to a linked account.	boolean	No
key	Identifier the credential value is stored and referenced under.	string	Yes
label	Human-readable name shown for this field.	string	Yes
placeholder	Example value shown in the empty input to hint the expected format.	string	No
readOnly	Whether the field is displayed but cannot be edited by the user. Default: false	boolean	Yes
required	Whether the field must have a value. Default: false	boolean	Yes
secret	Encrypt the value at rest and mask it in the UI. Default: false	boolean	Yes
tooltip	Additional guidance shown on hover for this field.	string	No
type	Input control rendered for this credential field. Allowed: text, password, text_area	enum	Yes
validation	Client-side validation constraint applied to the entered value.	object	No
value	Preset or computed value for the field, such as a fixed default or a JEXL expression.	string	No

setupFields.text | password | text_area.validation

Client-side validation constraint applied to the entered value.

Field	Description	Type	Required
errorMessage	Message shown when the value fails the pattern or format check.	string	No
format	Named format the entered value must match, standing in for a common regular expression. Provide this or pattern, not both. Allowed: email, url, uri, uuid, date, datetime	enum	No
pattern	Regular expression the entered value must match. Provide this or format, not both.	string	No

select

Field	Description	Type	Required
computed	Field value is a JEXL expression in value, evaluated at runtime rather than entered by the user.	boolean	No
description	Helper text explaining what the user should enter.	string	No
externalSystemAccountIdentifier	Value identifies the account in the external system, used to match incoming webhook events to a linked account.	boolean	No
key	Identifier the credential value is stored and referenced under.	string	Yes
label	Human-readable name shown for this field.	string	Yes
options	Selectable choices offered for this field.	object[]	Yes
placeholder	Example value shown in the empty input to hint the expected format.	string	No
readOnly	Whether the field is displayed but cannot be edited by the user. Default: false	boolean	Yes
required	Whether the field must have a value. Default: false	boolean	Yes
secret	Encrypt the value at rest and mask it in the UI. Default: false	boolean	Yes
tooltip	Additional guidance shown on hover for this field.	string	No
type	Input control rendered for this credential field.	string	Yes
value	Preset or computed value for the field, such as a fixed default or a JEXL expression.	string	No

setupFields.select.options

Selectable choices offered for this field.

Field	Description	Type	Required
label	Human-readable text shown for this option.	string	Yes
value	Value stored when this option is selected.	string	Yes

Examples

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.

Field	Description	Type	Required
anchor	Field key the notice is shown above. Only valid when position is top.	string	No
description	Text shown in the notice.	string	Yes
key	Identifier for the notice.	string	Yes
position	Whether the notice appears above or below the fields. Allowed: top, bottom Default: top	enum	Yes
type	Visual style of the notice. Allowed: warning, info Default: info	enum	Yes

Examples

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.

Field	Description	Type	Required
description	Help text guiding the user through connecting.	string	No
guides	Step-by-step connection guides.	object	No
link	URL to external setup documentation. Defaults to the generated connector guide on docs.stackone.com when omitted.	string	No

support.guides

Step-by-step connection guides.

Field	Description	Type	Required
config	Guide for the credentials end-users enter per connection.	object	No
setup	Guide for the credentials your team registers once.	object	No

support.guides.config

Guide for the credentials end-users enter per connection.

Field	Description	Type	Required
sections	Ordered sections making up the guide.	object[]	Yes
warning	Cautionary note shown at the top of the guide.	string	No

support.guides.config.sections

Ordered sections making up the guide.

Field	Description	Type	Required
applicableScopes	Scope names for which this section is shown. Space-separated, with any name that contains spaces wrapped in double quotes.	string	No
content	Introductory text for the section.	string	Yes
image	Illustrative image for the section.	object	No
list	Ordered items elaborating the section.	string[]	No
steps	Ordered steps making up the section.	object[]	No
title	Heading for this guide section.	string	Yes

support.guides.config.sections.image

Illustrative image for the section.

Field	Description	Type	Required
alt	Alternative text describing the image.	string	Yes
src	Image URL or a path relative to the connector.	string	Yes

support.guides.config.sections.steps

Ordered steps making up the section.

Field	Description	Type	Required
applicableScopes	Scope names for which this step is shown. Space-separated, with any name that contains spaces wrapped in double quotes.	string	No
content	Body text describing what the user should do.	string	Yes
displayScopes	Whether the step shows badges for the actions its scopes unlock.	boolean	No
image	Illustrative image for the step.	object	No
list	Ordered items elaborating the step.	string[]	No
title	Heading for this guide step.	string	Yes

support.guides.config.sections.steps.image

Illustrative image for the step.

Field	Description	Type	Required
alt	Alternative text describing the image.	string	Yes
src	Image URL or a path relative to the connector.	string	Yes

support.guides.setup

Guide for the credentials your team registers once.

Field	Description	Type	Required
sections	Ordered sections making up the guide.	object[]	Yes
warning	Cautionary note shown at the top of the guide.	string	No

support.guides.setup.sections

Ordered sections making up the guide.

Field	Description	Type	Required
applicableScopes	Scope names for which this section is shown. Space-separated, with any name that contains spaces wrapped in double quotes.	string	No
content	Introductory text for the section.	string	Yes
image	Illustrative image for the section.	object	No
list	Ordered items elaborating the section.	string[]	No
steps	Ordered steps making up the section.	object[]	No
title	Heading for this guide section.	string	Yes

support.guides.setup.sections.image

Illustrative image for the section.

Field	Description	Type	Required
alt	Alternative text describing the image.	string	Yes
src	Image URL or a path relative to the connector.	string	Yes

support.guides.setup.sections.steps

Ordered steps making up the section.

Field	Description	Type	Required
applicableScopes	Scope names for which this step is shown. Space-separated, with any name that contains spaces wrapped in double quotes.	string	No
content	Body text describing what the user should do.	string	Yes
displayScopes	Whether the step shows badges for the actions its scopes unlock.	boolean	No
image	Illustrative image for the step.	object	No
list	Ordered items elaborating the step.	string[]	No
title	Heading for this guide step.	string	Yes

support.guides.setup.sections.steps.image

Illustrative image for the step.

Field	Description	Type	Required
alt	Alternative text describing the image.	string	Yes
src	Image URL or a path relative to the connector.	string	Yes

Examples

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.

Field	Description	Type	Required
action	Action id or definition executed to test the connection.	union	Yes
condition	JEXL expression gating whether the test action runs.	string	No
required	Currently not in use. Default: true	boolean	Yes

testActions.action

Action id or definition executed to test the connection.

string

A string value.

actions

Same fields as actions.

Examples

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

Related

scopeDefinitions

Declare available scopes; profiles can pin requiredScopes.

baseUrl

Typically interpolates a $ here.

documentation

Connector-level external doc links, separate from per-auth guides.

Actions overview

Actions referenced by testActions and refresh_token must exist in actions[].