Reference for ConnectorAuth — four authentication types for connectors including OAuth2, SecretText, CustomAuth, and None.

Authentication

The ConnectorAuth namespace provides four factory methods for declaring how users authenticate with a connector. Each returns a frozen AuthDefinition that is passed to createConnector().

import { ConnectorAuth, AUTH_TYPES } from "@triggo/connector-sdk";

AUTH_TYPES Constant

const AUTH_TYPES = {
  OAUTH2: "OAUTH2",
  SECRET_TEXT: "SECRET_TEXT",
  CUSTOM: "CUSTOM",
  NONE: "NONE",
} as const;

ConnectorAuth.OAuth2

For services that support the OAuth 2.0 authorization code flow.

const auth = ConnectorAuth.OAuth2({
  authUrl: "https://service.com/oauth/authorize",
  tokenUrl: "https://service.com/oauth/token",
  scope: ["read", "write"],
  pkce: true,
  extraProps: {
    domain: Property.ShortText({
      displayName: "Domain",
      description: "Your account subdomain (e.g., mycompany).",
      required: true,
    }),
  },
  validateExtraProps: (props) => {
    if (!props["domain"]) {
      throw new Error("Domain is required");
    }
  },
});

OAuth2 Config Fields

Field	Type	Required	Description
`authUrl`	`string`	Yes	The OAuth2 authorization endpoint URL.
`tokenUrl`	`string`	Yes	The OAuth2 token exchange endpoint URL.
`scope`	`readonly string[]`	Yes	OAuth2 scopes to request.
`pkce`	`boolean`	No	Enable PKCE (Proof Key for Code Exchange). Recommended for public clients.
`extraProps`	`Record<string, PropertyDefinition>`	No	Additional fields the user must provide before OAuth flow (e.g., domain, region).
`validateExtraProps`	`(props: Record<string, string>) => void`	No	Synchronous validation for extra props. Throw to reject.

OAuth2Credentials

When an OAuth2 connector's run function executes, context.auth has this shape:

interface OAuth2Credentials {
  readonly accessToken: string;
  readonly refreshToken: string;
  readonly tokenType: string;
  readonly expiresIn?: number;
  readonly claimedAt: number;
  readonly props?: Record<string, string>;
  readonly data?: Record<string, unknown>;
}

Field	Type	Description
`accessToken`	`string`	The current access token. Triggo handles refresh automatically.
`refreshToken`	`string`	The refresh token for obtaining new access tokens.
`tokenType`	`string`	Token type, typically `"Bearer"`.
`expiresIn`	`number`	Token lifetime in seconds (from the token response).
`claimedAt`	`number`	Unix timestamp (ms) when the token was issued.
`props`	`Record<string, string>`	Values from `extraProps` (e.g., `{ domain: "mycompany" }`).
`data`	`Record<string, unknown>`	Non-sensitive extras from the token response (reserved for future use).

ConnectorAuth.SecretText

For services that use a single API key, token, or secret string.

const auth = ConnectorAuth.SecretText({
  displayName: "API Key",
  description: "Your API key from the service dashboard.",
  validate: async (authValue) => {
    const response = await fetch("https://api.example.com/me", {
      headers: { Authorization: `Bearer ${authValue.secret}` },
    });
    if (!response.ok) {
      throw new Error("Invalid API key");
    }
  },
});

SecretText Config Fields

Field	Type	Required	Description
`displayName`	`string`	Yes	Label shown in the connection UI.
`description`	`string`	No	Help text explaining where to find the secret.
`validate`	`(auth: { secret: string }) => Promise<void>`	No	Async validation function. Throw to reject the credential.

At runtime, context.auth has the shape { secret: string }.

ConnectorAuth.CustomAuth

For services that require multiple fields (e.g., username + password, or domain + API key).

const auth = ConnectorAuth.CustomAuth({
  props: {
    apiKey: Property.SecretText({
      displayName: "API Key",
      description: "Your API key.",
      required: true,
    }),
    region: Property.Dropdown({
      displayName: "Region",
      description: "Data center region.",
      required: true,
      options: [
        { label: "US", value: "us" },
        { label: "EU", value: "eu" },
      ],
    }),
  },
  validate: async (authValue) => {
    const apiKey = authValue["apiKey"] as string;
    const region = authValue["region"] as string;
    const response = await fetch(`https://${region}.api.example.com/verify`, {
      headers: { "X-Api-Key": apiKey },
    });
    if (!response.ok) {
      throw new Error("Invalid credentials");
    }
  },
});

CustomAuth Config Fields

Field	Type	Required	Description
`props`	`Record<string, PropertyDefinition>`	Yes	Custom fields using the Property system.
`validate`	`(auth: Record<string, unknown>) => Promise<void>`	No	Async validation. Receives resolved prop values. Throw to reject.

At runtime, context.auth is a Record<string, unknown> with keys matching the prop names.

ConnectorAuth.None

For connectors that require no authentication (e.g., public APIs, inbound webhooks).

const auth = ConnectorAuth.None();

No config is needed. At runtime, context.auth is undefined.

Choosing an Auth Type

Scenario	Auth Type
Service uses OAuth2 (e.g., AmoCRM, Google)	`ConnectorAuth.OAuth2`
Service uses a single API key or bot token	`ConnectorAuth.SecretText`
Service needs multiple credentials (e.g., domain + key)	`ConnectorAuth.CustomAuth`
No authentication needed (public API, inbound webhook)	`ConnectorAuth.None`

Authentication

On this page