bluenexus.ai Get API Key

Initiating OAuth for User Services

How to programmatically connect your users to external services (Google, Slack, GitHub, etc.) through BlueNexus.

The Flow

Your App                    BlueNexus                    Provider (e.g., Google)
   │                            │                               │
   │── POST /connections/       │                               │
   │   initiate ───────────────>│                               │
   │<── { authorizationUrl } ───│                               │
   │                            │                               │
   │── Redirect user ──────────────────────────────────────────>│
   │                            │          [User authorizes]    │
   │                            │<── callback with code ────────│
   │                            │── exchange code for tokens ──>│
   │                            │<── tokens ────────────────────│
   │                            │── encrypt & store             │
   │<── redirect to your app ───│                               │

Step 1: Initiate the Connection

curl -X POST https://api.bluenexus.ai/api/v1/connections/initiate \
  -H "Authorization: Bearer USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "google",
    "redirectUrl": "https://yourapp.com/connections/success"
  }'

Response:

{
  "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&scope=...&state=...",
  "providerMetadata": {
    "name": "Google Workspace",
    "logoUrl": "https://...",
    "description": "Gmail, Calendar, Drive, and more"
  }
}

Step 2: Redirect the User

Redirect the user to the authorizationUrl. They'll see the provider's OAuth consent screen (e.g., Google asking "Allow BlueNexus to access your Calendar?").

Step 3: Handle the Callback

After the user authorizes, the provider redirects to BlueNexus's callback endpoint. BlueNexus:

  1. Exchanges the authorization code for tokens
  2. Encrypts the tokens (AES-256-GCM)
  3. Stores the connection
  4. Redirects the user to your redirectUrl

Your app receives the redirect at https://yourapp.com/connections/success.

Step 4: Post-OAuth Fields (Some Providers)

Some providers require additional information after OAuth — for example, selecting a workspace or entering a subdomain.

Check for pending fields:

curl https://api.bluenexus.ai/api/v1/connections/pending/PENDING_ID/fields

If fields are returned, collect them from the user and finalize:

curl -X POST https://api.bluenexus.ai/api/v1/connections/pending/PENDING_ID/finalize \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "workspace": "my-workspace"
    }
  }'

Listing Available Providers

To show users which services they can connect:

curl https://api.bluenexus.ai/api/v1/providers

This endpoint is public (no auth required) and returns all available providers with their names, descriptions, logos, and categories.

Checking Connection Status

After a connection is created, check its status:

curl https://api.bluenexus.ai/api/v1/connections \
  -H "Authorization: Bearer USER_ACCESS_TOKEN"

See Connection Statuses for handling each status.

MCP Catalog Connection

For MCP catalog entries (external MCP servers), use a slightly different flow:

# Initiate OAuth for a catalog entry
curl -X POST https://api.bluenexus.ai/api/v1/connections/from-catalog/initiate-oauth \
  -H "Authorization: Bearer USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "catalogEntryId": "catalog-entry-123",
    "redirectUrl": "https://yourapp.com/connections/success"
  }'

# Or create a connection with a bearer token
curl -X POST https://api.bluenexus.ai/api/v1/connections/from-catalog \
  -H "Authorization: Bearer USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "catalogEntryId": "catalog-entry-123",
    "bearerToken": "the-mcp-server-token"
  }'

Next Steps