Integrations API

Manage which providers a user has connected. Use these endpoints to list available providers, check connection status, connect or disconnect a provider, and retrieve connection metadata.

Endpoints #

GET /integrations/providers #

Auth: Required (Bearer token). No request body.

Returns an array of all providers available on the platform. The connected field indicates whether the authenticated user has an active integration for that provider.

[
  {
    "id":          "prov_01abc",
    "name":        "Notion",
    "slug":        "notion",
    "description": "Connect pages, databases, and blocks",
    "authType":    "oauth2",
    "active":     true,
    "connected":  true
  },
  {
    "id":          "prov_01def",
    "name":        "Slack",
    "slug":        "slack",
    "description": "Send messages and read channels",
    "authType":    "oauth2",
    "active":     true,
    "connected":  false
  }
]

A value of connected: true means the authenticated user has an active integration for this provider. A value of connected: false means the provider is available but not yet connected by this user.

POST /integrations #

Auth: Required (Bearer token).

Use this endpoint for manual token integrations such as a GitHub Personal Access Token. For OAuth 2.0 providers use the OAuth flow instead.

{
  "providerId":  "prov_01ghi",
  "accessToken": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

{
  "id":         "int_01jkl",
  "provider":   "github",
  "status":     "connected",
  "createdAt":  "2026-03-14T09:00:00Z"
}

DELETE /integrations/:providerId #

Auth: Required (Bearer token). No request body.

Path parameter: providerId — the provider's UUID (not slug), obtained from GET /integrations/providers.

Returns 204 No Content on success.

OAuth Authorization Flow #

OAuth 2.0 providers (Notion, Slack, Google Drive, Gmail) require a browser-based authorization flow. AgentBridge handles the full code exchange and token storage.

1. Redirect to AgentBridge

   Your UI redirects the user to GET /oauth/:providerId. This requires a valid JWT session cookie or Authorization header.

2. AgentBridge builds the authorization URL

   AgentBridge constructs the provider's OAuth authorization URL with the correct scopes and a signed state parameter to prevent CSRF attacks.

3. Provider redirects back

   After the user grants access, the provider redirects to AgentBridge's registered callback URL with an authorization code.

4. Token exchange and storage

   AgentBridge exchanges the code for access and refresh tokens, encrypts them with AES-256-GCM, and stores them securely in the database.

5. Redirect to your frontend

   AgentBridge redirects the user's browser to your frontend at /oauth-callback?success=true (or ?success=false&error=... on failure).

Example authorization URL to initiate the flow:

GET https://api.agentbridge.in/oauth/prov_01abc
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...