OAuth flows for Meta, Google, TikTok, Shopify, and API key management for Stripe, PostHog, Klaviyo.

Connectors API

The Connectors API manages third-party integrations. OAuth connectors handle the full authorization flow, while API key connectors store and validate credentials.

Connector Types

OAuth Connectors

Full OAuth 2.0 flow with token refresh:

Connector	Provider	Scopes	Data
Meta Ads	Facebook/Instagram	`ads_management`, `pages_read`	Ad campaigns, performance, audiences
Google Ads	Google	`adwords`	Campaigns, keywords, performance
TikTok Ads	TikTok	`advertiser.read`	Campaign data, creative performance
Shopify	Shopify	`read_products`, `read_orders`	Products, orders, customers, analytics
GitHub	GitHub App	`repo`, `actions`	Repositories, deployments, CI/CD

API Key Connectors

Validated and stored credentials:

Connector	What It Provides
Stripe	Revenue analytics, subscription metrics, MRR/LTV
PostHog	Web analytics, funnels, user behavior
Klaviyo	Email/SMS campaigns, flows, segments
Google Analytics	GA4 traffic data, top pages, conversions
Gorgias	Customer support tickets, response times
Zendesk	Support tickets, agent performance

Deployment Connectors

Connector	What It Provides
Vercel	Deployment status, domains, build logs
Railway	Service status, deployment history
Figma	Design files, components, comments

OAuth Flow

1. Initiate

GET /api/oauth/{provider}/authorize?redirect_uri=https://app.meetreeve.com/cockpit/connectors
Authorization: Bearer <session-token>

# Response:
{
  "auth_url": "https://www.facebook.com/dialog/oauth?client_id=...&scope=ads_management"
}

2. Callback

After user authorizes, the provider redirects back:

GET /api/oauth/{provider}/callback?code=abc123&state=xyz

# Server exchanges code for tokens and stores them:
{
  "connected": true,
  "provider": "meta",
  "account_name": "Acme Ads Account"
}

3. Token Storage

OAuth tokens are stored in PostgreSQL, encrypted at rest:

class ConnectorToken(Base):
    __tablename__ = "connector_tokens"
    
    id = Column(String, primary_key=True)
    user_id = Column(String, nullable=False)
    provider = Column(String, nullable=False)  # "meta", "google", "tiktok"
    access_token = Column(String)              # Encrypted
    refresh_token = Column(String)             # Encrypted
    expires_at = Column(DateTime)
    scopes = Column(JSON)
    metadata = Column(JSON)                    # Account name, IDs, etc.

4. Token Refresh

OAuth tokens are refreshed automatically before expiry:

POST /api/connectors/{provider}/refresh
Authorization: Bearer <session-token>

API Key Connectors

Setting an API key

POST /api/connectors/connect
Authorization: Bearer <session-token>
Content-Type: application/json

{
  "provider": "stripe",
  "api_key": "sk_live_..."
}

The API validates the key before storing:

# Validation: try a simple API call
async def validate_stripe_key(api_key: str) -> bool:
    stripe.api_key = api_key
    try:
        stripe.Balance.retrieve()
        return True
    except stripe.AuthenticationError:
        return False

Listing connections

GET /api/connectors/list
Authorization: Bearer <session-token>

# Response:
{
  "connections": [
    { "provider": "meta", "type": "oauth", "status": "connected", "account": "Acme Ads" },
    { "provider": "stripe", "type": "api_key", "status": "connected" },
    { "provider": "shopify", "type": "oauth", "status": "disconnected" }
  ]
}

Disconnecting

DELETE /api/connectors/{provider}
Authorization: Bearer <session-token>

Deletes stored tokens and revokes OAuth access where possible.

Connector tokens are scoped per user. In a team, each member connects their own accounts. The dashboard aggregates data across all connected accounts for the team.

Gateway Integration

The gateway resolves connector tokens for agent tools:

// Token resolver: gateway asks services for the stored token
const token = await resolveConnectorToken("stripe", userId);
// Uses X-Reeve-Services-Token for service auth

This allows agents to use connected services (e.g., pull Stripe metrics, check Shopify orders) without storing API keys in the gateway config.

Connectors API

On this page