Connectors API
OAuth flows, available connectors, API key management, and webhook setup for third-party integrations.
Connectors API
The Connectors API manages third-party integrations — handling OAuth authorization flows, API key storage, token refresh, and connection lifecycle.
Authentication Methods
Reeve uses two methods depending on the platform:
| Method | Platforms | How It Works |
|---|---|---|
| OAuth 2.0 | Meta Ads, Google Ads, TikTok Ads, Shopify, GitHub, Slack | Click Connect → authorize on the platform → redirected back |
| API Key | Stripe, PostHog, Klaviyo, GA4, Gorgias, Zendesk, Vercel, Railway | Paste your key → validated and encrypted |
Available Connectors
Commerce & Payments
| Connector | Auth | Tools Enabled |
|---|---|---|
| Shopify | OAuth | reeve_shopify — products, orders, customers, revenue |
| Stripe | API Key | reeve_revenue — MRR, LTV, churn, subscriptions |
Advertising
| Connector | Auth | Tools Enabled |
|---|---|---|
| Meta Ads | OAuth | reeve_ads — campaigns, ROAS, creative performance |
| Google Ads | OAuth | reeve_ads — search/display campaigns, keywords |
| TikTok Ads | OAuth | reeve_ads — short-form video campaign data |
Marketing
| Connector | Auth | Tools Enabled |
|---|---|---|
| Klaviyo | API Key | reeve_email — campaigns, flows, segments, SMS |
Analytics
| Connector | Auth | Tools Enabled |
|---|---|---|
| PostHog | API Key | reeve_analytics — funnels, sessions, feature flags |
| Google Analytics | Service Account | reeve_analytics — traffic, top pages, conversions |
Customer Support
| Connector | Auth | Tools Enabled |
|---|---|---|
| Gorgias | API Key | reeve_support — tickets, response times, CSAT |
| Zendesk | API Key | reeve_support — tickets, agent performance |
Communication
| Connector | Auth | Tools Enabled |
|---|---|---|
| Slack | OAuth | Channel messaging, bot access |
Development
| Connector | Auth | Tools Enabled |
|---|---|---|
| GitHub | OAuth/App | Repos, PRs, CI/CD, deployments |
| Vercel | API Key | Deployment status, domains, build logs |
| Railway | API Key | Service status, deployment history |
| Figma | API Key | Design files, components |
OAuth Flow
Step 1: Initiate
The Cockpit sends a request to start the OAuth flow:
GET /api/oauth/{provider}/authorize
Authorization: Bearer <session-token>Returns an authorization URL that redirects the user to the platform's consent screen.
Step 2: User Authorizes
The user reviews permissions and clicks Approve on the platform. The platform redirects back with an authorization code.
Step 3: Token Exchange
Reeve exchanges the authorization code for access and refresh tokens:
GET /api/oauth/{provider}/callback?code=abc123&state=xyzTokens are encrypted and stored. The connection is now active.
Step 4: Automatic Refresh
OAuth tokens are refreshed automatically before they expire. Meta tokens last ~60 days; Google tokens refresh indefinitely as long as the refresh token is valid.
Security
- State parameter — CSRF protection with 10-minute TTL on state tokens
- HMAC verification — Shopify callbacks include HMAC signature verification
- Encrypted storage — Tokens encrypted at rest in PostgreSQL
API Key Flow
Connect
POST /api/connectors/connect
Authorization: Bearer <session-token>
{
"provider": "stripe",
"api_key": "sk_live_..."
}The key is validated against the provider's API before storage. Invalid keys return an immediate error.
List Connections
GET /api/connectors/list
Authorization: Bearer <session-token>Returns all connected platforms with status:
{
"connections": [
{ "provider": "meta", "type": "oauth", "status": "connected" },
{ "provider": "stripe", "type": "api_key", "status": "connected" },
{ "provider": "shopify", "type": "oauth", "status": "disconnected" }
]
}Disconnect
DELETE /api/connectors/{provider}
Authorization: Bearer <session-token>Deletes stored tokens and revokes OAuth access where the provider supports it.
Webhooks
Some connectors support inbound webhooks for real-time updates:
| Provider | Webhook Events |
|---|---|
| Shopify | Order created, product updated, inventory changed |
| Stripe | Payment succeeded, subscription updated, invoice created |
| GitHub | Push events, PR opened, deployment status |
Webhook URLs are automatically configured during connector setup. Events are routed to your agent as system events.
Multi-Brand Support
In multi-brand mode, connectors are scoped per brand. Each brand can have its own Shopify store, ad accounts, and analytics — all managed from a single Reeve account.
Connector credentials are scoped per user. Each team member connects their own accounts. The dashboard aggregates data across all connected accounts for the team.