External Users (B2B2C)

Overview

External Users (B2B2C) lets you build applications where YOUR end-users connect their tools (Gmail, Slack, etc.) through Agentic Fabriq — without needing their own Agentic Fabriq account.

You authenticate users in your own system, then use the External Users API to manage their tool connections and issue tokens for MCP calls.

How It Works

1. Your user authenticates with YOUR system (your own login flow)
2. You call the External Users API to create/register the user in Agentic Fabriq
3. You initiate an OAuth flow for the user to connect a tool (e.g., Gmail)
4. The user authorizes in their browser, granting your app access to their tool
5. You issue a JWT token for the user via the API
6. You include that token in MCP calls to execute tools on behalf of the user

Prerequisites

• Growth plan or above
• A registered application with b2b2c_enabled: true
• App credentials (app_id + app_secret) from application activation
• A callback URL configured on your application (b2b2c_oauth_callback_url)

Authentication

Two methods for authenticating API calls:

1. MCP Service Auth: Use the MCP client with your app credentials — the middleware automatically populates org/app context
2. App Credentials: Send X-App-Id and X-App-Secret headers directly

API Reference

Creating an External User

curl -X POST https://dashboard.agenticfabriq.com/api/v1/apps/{app_id}/external-users \
  -H "X-App-Id: your-app-id" \
  -H "X-App-Secret: your-app-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user-123",
    "email": "user@example.com",
    "display_name": "John Doe"
  }'copy

• external_user_id: Your own user identifier (max 255 chars, no :, /, or \)
• email and display_name are optional metadata

Initiating OAuth for a Tool

curl -X POST https://dashboard.agenticfabriq.com/api/v1/apps/{app_id}/external-users/{external_user_id}/oauth/gmail/initiate \
  -H "X-App-Id: your-app-id" \
  -H "X-App-Secret: your-app-secret"copy

• Returns oauth_url (plus state and connection_id) — redirect your user to that URL
• After authorization, Agentic Fabriq redirects to your b2b2c_oauth_callback_url with the result

Supported providers: gmail, google_drive, google_docs, google_sheets, google_slides, google_calendar, google_meet, google_forms, google_contacts, google_chat, slack, github, notion

Issuing a Token

curl -X POST https://dashboard.agenticfabriq.com/api/v1/apps/{app_id}/external-users/{external_user_id}/token \
  -H "X-App-Id: your-app-id" \
  -H "X-App-Secret: your-app-secret"copy

Response:

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 3600,
  "external_user_id": "user-123",
  "app_id": "your-app-id",
  "mcp_url": "https://dashboard.agenticfabriq.com/mcp"
}copy

• Use this token in Authorization: Bearer headers for MCP calls on behalf of the user
• Tokens expire in 1 hour — issue a new one as needed

Listing Connections

curl https://dashboard.agenticfabriq.com/api/v1/apps/{app_id}/external-users/{external_user_id}/connections \
  -H "X-App-Id: your-app-id" \
  -H "X-App-Secret: your-app-secret"copy

Disconnecting a Tool

curl -X POST https://dashboard.agenticfabriq.com/api/v1/apps/{app_id}/external-users/{external_user_id}/connections/{connection_id}/disconnect \
  -H "X-App-Id: your-app-id" \
  -H "X-App-Secret: your-app-secret"copy

Deleting an External User

curl -X DELETE https://dashboard.agenticfabriq.com/api/v1/apps/{app_id}/external-users/{external_user_id} \
  -H "X-App-Id: your-app-id" \
  -H "X-App-Secret: your-app-secret"copy

Complete Example

Python example using httpx:

import httpx

APP_ID = "your-app-id"
APP_SECRET = "your-app-secret"
BASE_URL = "https://dashboard.agenticfabriq.com/api/v1"
HEADERS = {"X-App-Id": APP_ID, "X-App-Secret": APP_SECRET}

# 1. Create external user
resp = httpx.post(f"{BASE_URL}/apps/{APP_ID}/external-users",
    headers=HEADERS,
    json={"external_user_id": "user-123", "email": "user@example.com"})
print(resp.json())

# 2. Initiate Gmail OAuth
resp = httpx.post(
    f"{BASE_URL}/apps/{APP_ID}/external-users/user-123/oauth/gmail/initiate",
    headers=HEADERS)
oauth_url = resp.json()["oauth_url"]
print(f"Redirect user to: {oauth_url}")

# 3. After user authorizes, issue a token
resp = httpx.post(
    f"{BASE_URL}/apps/{APP_ID}/external-users/user-123/token",
    headers=HEADERS)
token = resp.json()["access_token"]
mcp_url = resp.json()["mcp_url"]

# 4. Use token for MCP calls
from af_sdk import MCPClient
async with MCPClient(
    method="token",       # an Agentic Fabriq-minted external-user token
    app_id=APP_ID,
    app_secret=APP_SECRET,
    af_token=token,
    mcp_url=mcp_url
) as client:
    tools = await client.list_tools()
    result = await client.call_tool("google_gmail_list_messages", {
        "max_results": 5
    })copy

Security Notes