OAuth (recommended)

For Slack, Linear, GitHub, and Notion, the agent supports a one-click OAuth flow instead of copy-pasting API keys. OAuth is the recommended path because it:

Doesn’t require users to leave the dashboard to generate keys.
Records the workspace name / team / repo owner automatically (visible in GET /v1/cofounder/integrations).
Uses provider-issued tokens that can be revoked from the provider’s UI.
Lets you offer the same SaaS experience your users expect from any modern integrations page.

Webhook and ASC-write don’t need OAuth — they use a URL and the user’s existing ASC connection.

How the flow works

Frontend                        API                              Provider (Slack/Linear/…)
   │                             │                                       │
   │ 1. GET /oauth/slack/start  ─▶                                       │
   │                             │ create state row                       │
   │ ◀─ { authorizeUrl, state }  │                                       │
   │                             │                                       │
   │ 2. window.open(authorizeUrl) ───────────────────────────────────▶  │
   │                                                              user grants
   │                                                                     │
   │   3. provider redirects to /oauth/slack/callback?code=...&state=... │
   │                             ◀───────────────────────────────────────│
   │                             │ exchange code → token                  │
   │                             │ persist in cofounder_integrations      │
   │                             │ redirect to return_to?cofounder_oauth=success
   │ ◀──────────────────────────│                                       │
   │ show "Connected!" banner    │                                       │

Two endpoints, both under the cofounder router:

Method & path	Auth	Purpose
`GET /v1/cofounder/oauth/:provider/start`	API key / web JWT	Returns `{ authorizeUrl, state }` for the user to open
`GET /v1/cofounder/oauth/:provider/callback`	none (verified by `state`)	Exchanges code, persists credentials, redirects to `return_to`

:provider ∈ slack | linear | github | notion.

Frontend usage

async function connectSlack() {
  const res = await fetch(
    "https://api.appeeky.com/v1/cofounder/oauth/slack/start" +
      `?return_to=${encodeURIComponent(window.location.href)}`,
    { headers: { "X-API-Key": APPEEKY_KEY } }
  );
  const { data } = await res.json();
  // Redirect (or open in a popup) — provider will redirect back to your page
  window.location.href = data.authorizeUrl;
}

After the round-trip your page is reloaded with ?cofounder_oauth=success&provider=slack&account=Acme%20Workspace in the query string. Detect this in your page-load code, refresh the integrations list, and show a toast. Failure cases also redirect back, with ?cofounder_oauth=denied (user clicked Cancel) or ?cofounder_oauth=error&error=... (token exchange failed). Always inspect both shapes.

Server configuration

For each provider you want to support, create an OAuth client in the provider’s developer console. Set the Redirect URI to:

https://api.appeeky.com/v1/cofounder/oauth/<provider>/callback

Then set the corresponding env vars:

Provider	Env vars
Slack	`SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, optional `SLACK_OAUTH_BOT_SCOPES` (default: `chat:write,chat:write.public,channels:read,groups:read`)
Linear	`LINEAR_CLIENT_ID`, `LINEAR_CLIENT_SECRET`, optional `LINEAR_OAUTH_SCOPES` (default: `read,write,issues:create`)
GitHub	`GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, optional `GITHUB_OAUTH_SCOPES` (default: `repo`)
Notion	`NOTION_CLIENT_ID`, `NOTION_CLIENT_SECRET`

Cross-cutting:

Env var	Purpose	Default
`COFOUNDER_OAUTH_BASE_URL`	Public URL of THIS API (callback host)	`https://api.appeeky.com`
`COFOUNDER_OAUTH_DEFAULT_RETURN_TO`	Fallback return URL	`https://app.appeeky.com/integrations`
`COFOUNDER_OAUTH_RETURN_TO_ALLOWLIST`	Comma-separated host prefix allowlist for `return_to`	`https://app.appeeky.com,https://api.appeeky.com,http://localhost`

return_to MUST start with one of the allowlisted prefixes — otherwise it’s rejected (open-redirect guard).

What gets stored

After a successful OAuth round-trip, a row is upserted in cofounder_integrations:

provider             slack
auth_method          oauth
oauth_account_label  "Acme Workspace"        ← shown in the dashboard
oauth_external_id    "T012ABC"               ← team/workspace/repo id from provider
oauth_scope          "chat:write,channels:read,..."
oauth_expires_at     null                     ← Slack/Linear/GitHub/Notion all issue long-lived tokens
encrypted_credentials  { accessToken, botToken, teamId, ... }

encrypted_credentials is never returned by GET /v1/cofounder/integrations. The dashboard only sees the metadata above plus enabled and last_used_at.

Re-connect / Switch workspace

Re-running /oauth/:provider/start and completing the flow upserts the same (owner_email, provider) row — pointing the integration at the new workspace. The previous token is overwritten and effectively forgotten by the agent (it remains valid on the provider’s side until the user revokes it from there).

Disconnect

curl -X DELETE https://api.appeeky.com/v1/cofounder/integrations/slack \
  -H "X-API-Key: $APPEEKY_KEY"

This removes the credentials from our database. It does not revoke the token on Slack — go to your Slack workspace’s Apps page if you want to revoke it there too.

State row lifecycle

Each /start creates a cofounder_oauth_states row that:

Holds the random state, the user’s email, the provider, and (if applicable) the PKCE code_verifier.
Expires after 10 minutes.
Is deleted as soon as the callback consumes it (single-use).

Expired rows are purged opportunistically on every /start call.

Manual API-key path (still supported)

If you’d rather skip OAuth — for example, scripting your own integration — you can PUT /v1/cofounder/integrations/:provider with the credential JSON directly. See each provider’s page for the schema. OAuth-managed and manually-managed rows coexist; the latest one wins.

Get Started

Concepts

Knowledge Base

Capabilities

Integrations

API Reference

How the flow works

Frontend usage

Server configuration

What gets stored

Re-connect / Switch workspace

Disconnect

State row lifecycle

Manual API-key path (still supported)

​How the flow works

​Frontend usage

​Server configuration

​What gets stored

​Re-connect / Switch workspace

​Disconnect

​State row lifecycle

​Manual API-key path (still supported)

How the flow works

Frontend usage

Server configuration

What gets stored

Re-connect / Switch workspace

Disconnect

State row lifecycle

Manual API-key path (still supported)