Integrations

Agent calls custom tool
  → Worker MCP tool handler
    → POST /api/internal/tool-execute
      → Verify tool appears in approved agents.json payload
      → Resolve grant by workspaceId + appId + domain + keySlug
      → Follow that grant's credential binding
      → Read named secrets from Vault or local development storage
      → Inject named secrets and tool input into endpoint templates
      → Validate hostname, protocol, and resolved IPs
      → Execute HTTP request to external API
      → Return response to agent

Agent calls OAuth custom tool
  → Worker posts toolName, approved toolSpec, toolInput, runId
    → POST /api/internal/tool-execute
      → Verify tool appears in approved agents.json payload
      → Resolve grant by workspaceId + appId + domain + keySlug
      → Verify grant auth metadata matches the approved tool
      → Load app_agent_runs by workspaceId + appId + runId
      → Resolve triggering user from the run record
      → Load connected_account by workspaceId + userId + providerConfigId
      → Check scopes and revoked state
      → Refresh access token on demand if missing or near expiry
      → Inject Authorization: Bearer <access token> server-side
      → Validate hostname, protocol, and resolved IPs
      → Execute HTTP request to external API
      → Return bounded response to agent

type IntegrationDocument = {
  _id: string;
  workspaceId: string;
  appId: string;
  appName: string;
  name: string;              // "Linear"
  domain: string;            // "linear.app"
  keySlug: string;           // "default", "write-access", etc.
  keyName: string;           // "Linear read key for Roadmap Tracker"
  capabilityLabel: string;   // "Linear read"
  auth:
    | { type: "static_secret" }
    | {
        type: "oauth2";
        providerKey: string;
        identity: "triggering_user";
        authorizationUrl: string;
        tokenUrl: string;
        scopes: string[];
        tokenAuthMethod: "client_secret_post" | "client_secret_basic" | "none";
        authorizationParams?: Record<string, string>;
        tokenParams?: Record<string, string>;
      };
  accessLevel: "read" | "write" | "delete_admin" | "mixed" | "unknown";
  credentialBinding: { mode: "none" } | { mode: "dedicated"; credentialId: string };
  permissionGroups: IntegrationPermissionGroup[];
  secretRequirements: IntegrationSecretRequirement[];
  setupInstructions: IntegrationSetupInstructions | null;
  requestedByUserId: string;
  requestedByUserName: string;
  requestedAt: Date;
  createdAt: Date;
  updatedAt: Date;
};

type IntegrationCredentialDocument = {
  _id: string;
  workspaceId: string;
  domain: string;
  credentialName: string;
  configured: boolean;
  vaultSecretIds: Record<string, string>;
  localSecrets: Record<string, string>;
  configuredPermissionGroups: IntegrationPermissionGroup[];
  configuredSecrets: string[];
  capabilityFingerprint: string;
  linkedGrantIds: string[];
  createdAt: Date;
  updatedAt: Date;
};

type OAuthProviderConfigDocument = {
  _id: string;
  workspaceId: string;
  providerKey: string;              // "google", "microsoft", "zoom", etc.
  displayName: string;
  authorizationUrl: string;
  tokenUrl: string;
  tokenAuthMethod: "client_secret_post" | "client_secret_basic" | "none";
  defaultAuthorizationParams?: Record<string, string>;
  defaultTokenParams?: Record<string, string>;
  clientId: string | null;
  clientSecretRef: string | null;   // WorkOS Vault or local encrypted ref
  configured: boolean;
  configuredAt?: Date | null;
  createdAt: Date;
  updatedAt: Date;
};

type ConnectedAccountDocument = {
  _id: string;
  workspaceId: string;
  userId: string;
  providerConfigId: string;
  providerKey: string;
  source: "customer_oauth" | "local_direct" | "hosted_broker";
  externalSubject?: string | null;
  accountEmail?: string | null;
  accountName?: string | null;
  grantedScopes: string[];
  refreshTokenRef?: string | null;  // WorkOS Vault or local encrypted ref
  accessTokenRef?: string | null;   // optional short-lived cache
  accessTokenExpiresAt?: Date | null;
  lastRefreshAt?: Date | null;
  lastRefreshError?: string | null;
  revokedAt?: Date | null;
  createdAt: Date;
  updatedAt: Date;
};

{
  "integrations": [
    {
      "name": "Slack",
      "domain": "slack.com",
      "keySlug": "default",
      "keyName": "Slack post key for this app",
      "capabilityLabel": "Slack post",
      "why": "This app sends Slack messages.",
      "permissionGroups": [
        {
          "name": "Write",
          "description": "Allows the app to post messages into selected Slack channels.",
          "permissions": ["chat:write"]
        }
      ],
      "secrets": [
        {
          "name": "SLACK_BOT_TOKEN",
          "label": "Slack bot token",
          "description": "Paste the Bot User OAuth Token that starts with xoxb-.",
          "required": true
        }
      ],
      "setupInstructions": {
        "overview": "Create or update a Slack app, grant the bot scope, install it to the workspace, and paste the bot token in Second.",
        "steps": [
          {
            "title": "Open Slack apps",
            "description": "Go to [Slack | API apps](https://api.slack.com/apps) and create a new app or open the existing app you want Second to use.",
            "url": "https://api.slack.com/apps"
          }
        ]
      }
    }
  ]
}

{
  "integrations": [
    {
      "name": "Google Gmail",
      "domain": "googleapis.com",
      "keySlug": "gmail-read",
      "keyName": "Google OAuth client for this app",
      "capabilityLabel": "Gmail metadata search",
      "why": "This app searches the triggering user's Gmail metadata.",
      "auth": {
        "type": "oauth2",
        "providerKey": "google",
        "identity": "triggering_user",
        "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
        "tokenUrl": "https://oauth2.googleapis.com/token",
        "scopes": ["https://www.googleapis.com/auth/gmail.metadata"],
        "tokenAuthMethod": "client_secret_post",
        "authorizationParams": {
          "access_type": "offline",
          "prompt": "consent"
        }
      },
      "permissionGroups": [
        {
          "name": "Read-only",
          "description": "Allows the app to search Gmail metadata for the connected user.",
          "permissions": ["https://www.googleapis.com/auth/gmail.metadata"]
        }
      ],
      "setupInstructions": {
        "overview": "Create a customer-owned OAuth app, add Second's redirect URI, configure the client ID/secret in Second, then each user connects their own account.",
        "steps": [
          {
            "title": "Create OAuth client",
            "description": "Create a provider OAuth app with the listed scopes. For Google Workspace enterprise deployments, use an Internal app when appropriate."
          },
          {
            "title": "Add redirect URI",
            "description": "Copy the redirect URI shown in Second's integration settings into the provider OAuth app."
          },
          {
            "title": "Configure and connect",
            "description": "Paste the client ID and client secret into Second, then connect your own account."
          }
        ]
      }
    }
  ]
}

SECOND_DEV_PORTLESS=0 PORT=4198 npm run dev

{
  "type": "custom",
  "name": "linear_search_issues",
  "integration": {
    "name": "Linear",
    "domain": "linear.app",
    "keySlug": "default"
  },
  "endpoint": {
    "method": "POST",
    "url": "https://api.linear.app/graphql",
    "headers": {
      "Authorization": "{{secrets.LINEAR_API_KEY}}"
    }
  },
  "mockData": [{ "issues": [] }]
}

{
  "type": "custom",
  "name": "gmail_search_messages",
  "integration": {
    "name": "Google Gmail",
    "domain": "googleapis.com",
    "keySlug": "gmail-read",
    "auth": {
      "type": "oauth2",
      "providerKey": "google",
      "identity": "triggering_user",
      "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
      "tokenUrl": "https://oauth2.googleapis.com/token",
      "scopes": ["https://www.googleapis.com/auth/gmail.metadata"],
      "tokenAuthMethod": "client_secret_post",
      "authorizationParams": {
        "access_type": "offline",
        "prompt": "consent"
      }
    }
  },
  "endpoint": {
    "method": "GET",
    "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages",
    "queryParams": {
      "q": "{{query}}",
      "maxResults": "10"
    }
  },
  "mockData": [{ "messages": [] }]
}