Plugin Credentials Guide

This guide provides detailed instructions for obtaining all required credentials for each Corsair plugin. Each plugin section includes step-by-step instructions, required vs optional credentials, and webhook setup where applicable.

Overview

Corsair plugins require different types of credentials depending on their authentication method:

• API Keys: Static keys or tokens used for authentication (e.g., Slack bot tokens, Linear API keys)
• OAuth 2.0: Client ID, Client Secret, Access Token, and Refresh Token for user authorization
• Webhook Secrets: Secrets used to verify incoming webhook requests

For general information about how Corsair handles authentication, see Authentication.

Table of Contents

• Slack
• GitHub
• Gmail
• Google Sheets
• Google Drive
• Google Calendar
• HubSpot
• Linear
• PostHog
• Resend

Slack

The Slack plugin supports both API key (bot token) and OAuth 2.0 authentication methods.

Authentication Methods

• api_key (default) - Bot token authentication
• oauth_2 - OAuth 2.0 user authentication

API Key Authentication (Bot Token)

Step 1: Create a Slack App

1. Go to api.slack.com/apps
2. Click Create New App
3. Choose From scratch
4. Enter your app name and select your workspace
5. Click Create App

Step 2: Configure Bot Token Scopes

1. In your app settings, go to OAuth & Permissions in the left sidebar
2. Scroll to Scopes → Bot Token Scopes
3. Add the required scopes:
   • channels:read - View basic information about public channels
   • channels:write - Manage public channels
   • chat:write - Send messages
   • files:read - View files shared in channels
   • files:write - Upload, edit, and delete files
   • users:read - View people in a workspace
   • reactions:write - Add and remove emoji reactions
   • Add any other scopes your application needs

Step 3: Install App to Workspace

1. Scroll to the top of the OAuth & Permissions page
2. Click Install to Workspace
3. Review the permissions and click Allow

Step 4: Copy Bot Token

1. After installation, you'll be redirected back to OAuth & Permissions
2. Under OAuth Tokens for Your Workspace, find Bot User OAuth Token
3. Click Copy to copy the token (starts with xoxb-)
4. Store this token securely

Example Configuration:

slack({
    authType: "api_key",
    key: process.env.SLACK_BOT_TOKEN,
})

OAuth 2.0 Authentication

Step 1: Create a Slack App

Follow steps 1-3 from the API Key Authentication section above.

Step 2: Configure OAuth Settings

1. Go to OAuth & Permissions in the left sidebar
2. Under Redirect URLs, click Add New Redirect URL
3. Add your OAuth redirect URL (e.g., https://yourapp.com/auth/slack/callback)
4. Click Save URLs

Step 3: Get Client Credentials

1. Scroll to App Credentials section
2. Copy the Client ID and Client Secret
3. Store these securely

Example Configuration:

slack({
    authType: "oauth_2",
})

The plugin will automatically retrieve access tokens from your database after users complete the OAuth flow.

Webhook Signing Secret

Step 1: Enable Event Subscriptions

1. In your Slack app settings, go to Event Subscriptions in the left sidebar
2. Toggle Enable Events to On
3. Enter your Request URL (e.g., https://yourapp.com/api/webhook)
4. Slack will send a verification request - ensure your endpoint handles it

Step 2: Subscribe to Bot Events

1. Scroll to Subscribe to bot events
2. Click Add Bot User Event
3. Add events you want to receive:
   • message.channels - Messages posted to channels
   • channel_created - A channel was created
   • reaction_added - A reaction was added
   • team_join - A new member joined
   • user_change - A user's profile was updated
   • file_created - A file was created
   • file_public - A file was made public
   • file_shared - A file was shared

Step 3: Get Signing Secret

1. Scroll to the top of the Event Subscriptions page
2. Under Signing Secret, click Show and copy the secret
3. Store this securely

Example Configuration:

slack({
    signingSecret: process.env.SLACK_SIGNING_SECRET,
})

Required Credentials Summary

GitHub

The GitHub plugin supports both API key (Personal Access Token) and OAuth 2.0 authentication methods.

Authentication Methods

• api_key - Personal Access Token authentication
• oauth_2 - OAuth App authentication

API Key Authentication (Personal Access Token)

Step 1: Create Personal Access Token

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click Generate new token → Generate new token (classic)
3. Give your token a descriptive name
4. Set an expiration (or select "No expiration" for long-lived tokens)
5. Select the required scopes:
   • repo - Full control of private repositories
   • read:org - Read org and team membership
   • read:user - Read user profile data
   • workflow - Update GitHub Action workflows
   • Add any other scopes your application needs
6. Click Generate token
7. Important: Copy the token immediately - you won't be able to see it again
8. Store the token securely

Example Configuration:

github({
    authType: "api_key",
    credentials: {
        token: process.env.GITHUB_TOKEN,
    },
})

OAuth 2.0 Authentication

Step 1: Register OAuth App

1. Go to GitHub Settings → Developer settings → OAuth Apps
2. Click New OAuth App
3. Fill in the application details:
   • Application name: Your app name
   • Homepage URL: Your application URL
   • Authorization callback URL: Your OAuth callback URL (e.g., https://yourapp.com/auth/github/callback)
4. Click Register application

Step 2: Get Client Credentials

1. After registration, you'll see your Client ID
2. Click Generate a new client secret
3. Copy the Client ID and Client Secret
4. Store these securely

Example Configuration:

github({
    authType: "oauth_2",
    credentials: {
        clientId: process.env.GITHUB_CLIENT_ID,
        clientSecret: process.env.GITHUB_CLIENT_SECRET,
    },
})

Webhook Secret

Step 1: Create Webhook

1. Go to your repository on GitHub
2. Navigate to Settings → Webhooks
3. Click Add webhook
4. Configure the webhook:
   • Payload URL: Your webhook endpoint (e.g., https://yourapp.com/api/webhook)
   • Content type: application/json
   • Secret: Generate a random secret string (save this)
   • Events: Select the events you want to receive:
     • Pull requests
     • Pushes
     • Issues
     • Stars
     • Releases
5. Click Add webhook

Step 2: Store Webhook Secret

Copy the secret you generated and store it securely.

Example Configuration:

github({
    webhookSecret: process.env.GITHUB_WEBHOOK_SECRET,
})

Required Credentials Summary

Gmail

The Gmail plugin uses OAuth 2.0 authentication exclusively.

Authentication Method

• oauth_2 (default) - OAuth 2.0 authentication

OAuth 2.0 Setup

Step 1: Create Google Cloud Project

1. Go to Google Cloud Console
2. Click Select a project → New Project
3. Enter a project name and click Create
4. Wait for the project to be created and select it

Step 2: Enable Gmail API

1. In the Google Cloud Console, go to APIs & Services → Library
2. Search for "Gmail API"
3. Click on Gmail API
4. Click Enable

Step 3: Create OAuth 2.0 Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. If prompted, configure the OAuth consent screen:
   • Choose External (unless you have a Google Workspace)
   • Fill in the required information:
     • App name
     • User support email
     • Developer contact information
   • Add scopes:
     • https://www.googleapis.com/auth/gmail.readonly
     • https://www.googleapis.com/auth/gmail.send
     • https://www.googleapis.com/auth/gmail.modify
     • https://www.googleapis.com/auth/gmail.compose
   • Add test users (for testing)
   • Click Save and Continue through all steps
4. Back in Credentials, click Create Credentials → OAuth client ID
5. Select Web application
6. Configure:
   • Name: Your application name
   • Authorized redirect URIs: Add your callback URL (e.g., https://yourapp.com/auth/gmail/callback)
7. Click Create
8. Copy the Client ID and Client Secret
9. Store these securely

Example Configuration:

gmail({
    authType: "oauth_2",
    credentials: {
        clientId: process.env.GMAIL_CLIENT_ID,
        clientSecret: process.env.GMAIL_CLIENT_SECRET,
    },
})

The plugin will automatically handle access token and refresh token storage after users complete the OAuth flow.

Required Credentials Summary

Google Sheets

The Google Sheets plugin uses OAuth 2.0 authentication exclusively.

Authentication Method

• oauth_2 (default) - OAuth 2.0 authentication

OAuth 2.0 Setup

Step 1: Create Google Cloud Project

1. Go to Google Cloud Console
2. Click Select a project → New Project
3. Enter a project name and click Create
4. Wait for the project to be created and select it

Step 2: Enable Google Sheets API

1. In the Google Cloud Console, go to APIs & Services → Library
2. Search for "Google Sheets API"
3. Click on Google Sheets API
4. Click Enable

Step 3: Create OAuth 2.0 Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. If prompted, configure the OAuth consent screen (see Gmail section for details)
4. Select Web application
5. Configure:
   • Name: Your application name
   • Authorized redirect URIs: Add your callback URL (e.g., https://yourapp.com/auth/googlesheets/callback)
6. Click Create
7. Copy the Client ID and Client Secret
8. Store these securely

Example Configuration:

googlesheets({
    authType: "oauth_2",
    credentials: {
        clientId: process.env.GOOGLE_SHEETS_CLIENT_ID,
        clientSecret: process.env.GOOGLE_SHEETS_CLIENT_SECRET,
    },
})

Required Credentials Summary

Google Drive

The Google Drive plugin uses OAuth 2.0 authentication exclusively.

Authentication Method

• oauth_2 (default) - OAuth 2.0 authentication

OAuth 2.0 Setup

Step 1: Create Google Cloud Project

1. Go to Google Cloud Console
2. Click Select a project → New Project
3. Enter a project name and click Create
4. Wait for the project to be created and select it

Step 2: Enable Google Drive API

1. In the Google Cloud Console, go to APIs & Services → Library
2. Search for "Google Drive API"
3. Click on Google Drive API
4. Click Enable

Step 3: Create OAuth 2.0 Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. If prompted, configure the OAuth consent screen (see Gmail section for details)
4. Select Web application
5. Configure:
   • Name: Your application name
   • Authorized redirect URIs: Add your callback URL (e.g., https://yourapp.com/auth/googledrive/callback)
6. Click Create
7. Copy the Client ID and Client Secret
8. Store these securely

Example Configuration:

googledrive({
    authType: "oauth_2",
    credentials: {
        clientId: process.env.GOOGLE_DRIVE_CLIENT_ID,
        clientSecret: process.env.GOOGLE_DRIVE_CLIENT_SECRET,
    },
})

Required Credentials Summary

Google Calendar

The Google Calendar plugin uses OAuth 2.0 authentication exclusively.

Authentication Method

• oauth_2 (default) - OAuth 2.0 authentication

OAuth 2.0 Setup

Step 1: Create Google Cloud Project

1. Go to Google Cloud Console
2. Click Select a project → New Project
3. Enter a project name and click Create
4. Wait for the project to be created and select it

Step 2: Enable Google Calendar API

1. In the Google Cloud Console, go to APIs & Services → Library
2. Search for "Google Calendar API"
3. Click on Google Calendar API
4. Click Enable

Step 3: Create OAuth 2.0 Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. If prompted, configure the OAuth consent screen (see Gmail section for details)
4. Select Web application
5. Configure:
   • Name: Your application name
   • Authorized redirect URIs: Add your callback URL (e.g., https://yourapp.com/auth/googlecalendar/callback)
6. Click Create
7. Copy the Client ID and Client Secret
8. Store these securely

Example Configuration:

googlecalendar({
    authType: "oauth_2",
    credentials: {
        clientId: process.env.GOOGLE_CALENDAR_CLIENT_ID,
        clientSecret: process.env.GOOGLE_CALENDAR_CLIENT_SECRET,
    },
})

Required Credentials Summary

HubSpot

The HubSpot plugin supports both API key and OAuth 2.0 authentication methods.

Authentication Methods

• api_key - Private App API key authentication
• oauth_2 - OAuth 2.0 authentication

API Key Authentication (Private App)

Step 1: Create Private App

1. Go to HubSpot Settings
2. Navigate to Integrations → Private Apps
3. Click Create a private app
4. Enter an app name
5. Click Create app

Step 2: Configure Scopes

1. In your private app settings, go to Scopes tab
2. Select the required scopes:
   • crm.objects.contacts.read
   • crm.objects.contacts.write
   • crm.objects.companies.read
   • crm.objects.companies.write
   • crm.objects.deals.read
   • crm.objects.deals.write
   • crm.objects.tickets.read
   • crm.objects.tickets.write
   • engagements.read
   • engagements.write
   • Add any other scopes your application needs
3. Click Save

Step 3: Get API Key

1. Go to the Overview tab
2. Under API key, click Show to reveal the key
3. Copy the API key
4. Store it securely

Example Configuration:

hubspot({
    authType: "api_key",
    credentials: {
        apiKey: process.env.HUBSPOT_API_KEY,
    },
})

OAuth 2.0 Authentication

Step 1: Create App

1. Go to HubSpot Developer Portal
2. Click Create app
3. Enter your app name and click Create app

Step 2: Configure OAuth Settings

1. In your app settings, go to Auth tab
2. Under Redirect URLs, click Add
3. Add your OAuth redirect URL (e.g., https://yourapp.com/auth/hubspot/callback)
4. Click Save

Step 3: Get Client Credentials

1. In the Auth tab, you'll see your Client ID
2. Click Show next to Client Secret to reveal it
3. Copy the Client ID and Client Secret
4. Store these securely

Example Configuration:

hubspot({
    authType: "oauth_2",
    credentials: {
        clientId: process.env.HUBSPOT_CLIENT_ID,
        clientSecret: process.env.HUBSPOT_CLIENT_SECRET,
    },
})

Webhook Secret

Step 1: Create Webhook Subscription

1. Go to HubSpot Settings
2. Navigate to Integrations → Private Apps
3. Select your private app (or create one if needed)
4. Go to Webhooks tab
5. Click Create subscription
6. Configure:
   • Event type: Select from:
     • Contact created/updated/deleted
     • Company created/updated/deleted
     • Deal created/updated/deleted
     • Ticket created/updated/deleted
   • Webhook URL: Your webhook endpoint (e.g., https://yourapp.com/api/webhook)
7. Click Save
8. If a webhook secret is provided, copy it and store securely

Example Configuration:

hubspot({
    webhookSecret: process.env.HUBSPOT_WEBHOOK_SECRET,
})

Required Credentials Summary

Linear

The Linear plugin uses API key authentication.

Authentication Method

• api_key (default) - Personal API key authentication

API Key Setup

Step 1: Generate API Key

1. Go to Linear Settings → API
2. Navigate to the API section
3. Under Personal API keys, click Create API key
4. Give your key a name (e.g., "Corsair Integration")
5. Copy the API key immediately
6. Important: Store the key securely - you won't be able to see it again

Example Configuration:

linear({
    authType: "api_key",
    key: process.env.LINEAR_API_KEY,
})

Webhook Secret

Step 1: Create Webhook

1. Go to Linear Settings → API
2. Navigate to Webhooks section
3. Click Create Webhook
4. Configure:
   • Label: Your webhook name
   • URL: Your webhook endpoint (e.g., https://yourapp.com/api/webhook)
   • Resource types: Select:
     • Issues
     • Comments
     • Projects
5. Click Create Webhook
6. After creation, copy the Signing Secret shown
7. Store it securely

Example Configuration:

linear({
    webhookSecret: process.env.LINEAR_WEBHOOK_SECRET,
})

Required Credentials Summary

PostHog

The PostHog plugin uses API key authentication.

Authentication Method

• api_key (default) - Project API key authentication

API Key Setup

Step 1: Get Project API Key

1. Log in to your PostHog account
2. Navigate to Project Settings
3. Click on Project API Key in the left sidebar
4. Copy your Project API Key
5. Store it securely

Example Configuration:

posthog({
    authType: "api_key",
    key: process.env.POSTHOG_API_KEY,
})

Personal API Key (Optional)

For advanced API access, you can also create a Personal API Key:

1. In PostHog, click on your profile icon (top right)
2. Go to Personal API Keys
3. Click Create Personal API Key
4. Give it a name and copy the key
5. Important: Store this key securely - you won't be able to see it again

Webhook Secret

Step 1: Create Webhook Destination

1. Go to your PostHog project settings
2. Navigate to Data Pipelines → Destinations
3. Click New destination
4. Select Webhook as the destination type
5. Configure:
   • Webhook URL: Your webhook endpoint (e.g., https://yourapp.com/api/webhook)
   • Events: Select event_captured or all events
6. Click Save
7. If a webhook secret is provided, copy it and store securely

Example Configuration:

posthog({
    webhookSecret: process.env.POSTHOG_WEBHOOK_SECRET,
})

Required Credentials Summary

Resend

The Resend plugin uses API key authentication.

Authentication Method

• api_key (default) - API key authentication

API Key Setup

Step 1: Get API Key

1. Log in to your Resend account
2. Navigate to API Keys in the dashboard
3. Click Create API Key
4. Give your key a name (e.g., "Corsair Integration")
5. Select the required permissions
6. Click Create
7. Copy the API key immediately
8. Important: Store the key securely - you won't be able to see it again

Example Configuration:

resend({
    authType: "api_key",
    key: process.env.RESEND_API_KEY,
})

Webhook Secret

Step 1: Create Webhook

1. In your Resend dashboard, go to Webhooks
2. Click Add Webhook
3. Configure:
   • Webhook URL: Your webhook endpoint (e.g., https://yourapp.com/api/webhook)
   • Events: Select the events you want to receive:
     • email.sent
     • email.delivered
     • email.bounced
     • email.opened
     • email.clicked
     • email.complained
     • email.failed
     • email.received
     • domain.created
     • domain.updated
4. Click Add Webhook
5. After creation, copy the Signing Secret shown
6. Store it securely

Example Configuration:

resend({
    webhookSecret: process.env.RESEND_WEBHOOK_SECRET,
})

Required Credentials Summary

Security Best Practices

When working with credentials:

1. Never commit credentials to version control - Use environment variables or a secrets manager
2. Use environment variables - Store credentials in .env files (and add .env to .gitignore)
3. Rotate credentials regularly - Periodically regenerate API keys and tokens
4. Use least privilege - Only grant the minimum scopes/permissions needed
5. Monitor usage - Regularly check for unauthorized access or unusual activity
6. Use secrets managers - For production, consider using AWS Secrets Manager, HashiCorp Vault, or similar

For more information on how Corsair handles credential security, see Authentication.