Connections API

Manage user connections to external services.

Base URL: https://api.bluenexus.ai/api/v1/connections

POST /connections/initiate

Start the OAuth flow to connect a user to a service.

Auth: Bearer token with connections scope

Request:

{
  "providerId": "google",
  "redirectUrl": "https://yourapp.com/connections/success",
  "providerParams": {}
}

Response (200):

{
  "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth?...",
  "providerMetadata": {
    "name": "Google Workspace",
    "logoUrl": "/provider-logos/google.svg",
    "description": "Gmail, Calendar, Drive, and more"
  }
}

Redirect the user to authorizationUrl.

---

GET /connections/callback

OAuth callback handler. BlueNexus handles this internally — the provider redirects here after the user authorizes.

Auth: None (called by the provider)

Query Parameters: code, state, error, error_description

---

GET /connections

List the authenticated user's connections.

Auth: Bearer token with connections scope

Query Parameters:

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	20	Items per page (max 100)
sortBy	string	createdAt	Sort field
sortOrder	string	desc	asc or desc

Response (200):

{
  "data": [
    {
      "id": "conn-abc123",
      "accountId": "account-xyz",
      "providerId": "google",
      "providerUserId": "user@gmail.com",
      "scopes": ["calendar.read", "drive.read"],
      "status": "active",
      "expiresAt": "2026-05-13T10:00:00Z",
      "canRefresh": true,
      "metadata": {
        "displayName": "John Doe",
        "email": "john@gmail.com",
        "avatar": "https://...",
        "providerName": "Google Workspace",
        "providerIcon": "/provider-logos/google.svg"
      },
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-04-13T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "hasMore": false
  }
}

---

GET /connections/:connectionId

Get a specific connection.

Auth: Bearer token with connections scope

---

PUT /connections/:connectionId/refresh

Refresh an expired connection's OAuth tokens.

Auth: Bearer token with connections scope

Response (200): Updated connection object with new status.

---

DELETE /connections/:connectionId

Delete a connection (revokes access).

Auth: Bearer token with connections scope

---

POST /connections/from-catalog/initiate-oauth

Initiate OAuth for an MCP catalog entry.

Auth: Bearer token with connections scope

{
  "catalogEntryId": "catalog-entry-123",
  "redirectUrl": "https://yourapp.com/callback"
}

---

POST /connections/from-catalog

Create a connection from an MCP catalog entry using a bearer token.

Auth: Bearer token with connections scope

{
  "catalogEntryId": "catalog-entry-123",
  "bearerToken": "mcp-server-token"
}

---

GET /connections/pending/:pendingId/fields

Get post-OAuth fields required to finalize a connection.

Auth: None

---

POST /connections/pending/:pendingId/finalize

Finalize a connection with post-OAuth fields.

Auth: None

{
  "fields": {
    "workspace": "my-workspace"
  }
}

Connection Statuses

Status	Description
active	Working normally
expired	Tokens expired — call refresh
error	Error occurred — may need reconnect
revoked	Access revoked — must reconnect