B2B Partner Adapter

Use the B2B partner adapter when your product serves many downstream customers from one trusted backend. Your server owns the Hive API key, derives subject identity from your own auth system, signs that subject context, and Hive stores monitors, memory facts, alerts, and reports under the resolved subject boundary. Downstream users do not need their own Hive API keys.

Who this is for

Use this path when all three are true:

• Your application authenticates its own customers.
• Your backend, not the browser or model, can derive the workspace and end-user identity.
• You want Hive stateful tools to remember per-customer monitors, watchlists, alerts, reports, or memory facts.

If every end user has a direct Hive account and API key, use Stateful Monitoring without signed subject headers.

Mental model

Hive resolves state by the authenticated Hive owner plus the signed subject. Direct users get the default subject self; B2B partners send an explicit tenantId and endUserId.

Partner checklist

1. Create or use a Hive account.
2. Create a B2B-enabled Hive key and keep the API key server-side.
3. Store the subject signing secret server-side as HIVE_SUBJECT_SIGNING_SECRET.
4. Map your workspace, organization, or tenant id to tenantId.
5. Map your authenticated user id to endUserId.
6. Use the TypeScript adapter helper (npm install hive-mcp-client), or use the REST fallback with signed headers.
7. Run a readiness check from the same backend environment that will sign subject headers.
8. Smoke-test with a low-risk stateful tool such as hive_list_monitors before creating monitors.

Never ask the model or downstream user to provide __hive_user_id, __hive_subject_id, tenant ids, or signing headers. Build subject context from trusted server state.

Create a B2B-enabled key

Create the key from an authenticated server-side account session. Set b2b_subjects_enabled: true so Hive issues a signing secret for downstream subject headers:

curl -X POST https://mcp.hiveintelligence.xyz/api/v1/keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HIVE_DASHBOARD_ACCESS_TOKEN" \
  -H "Idempotency-Key: b2b-key-setup-001" \
  -d '{
    "name": "Partner production adapter",
    "b2b_subjects_enabled": true
  }'

The response returns the Hive API key once and, for B2B-enabled keys, can also return subject_signing_secret. Store both in server-side secret storage:

{
  "ok": true,
  "data": {
    "key": "hive_live_...",
    "key_id": "key_...",
    "b2b_subjects_enabled": true,
    "subject_signing_secret": "hive_subject_...",
    "warning": "Save this key — it will not be shown again."
  }
}

Set the returned values as HIVE_API_KEY and HIVE_SUBJECT_SIGNING_SECRET in the backend that will sign subject headers.

Preflight readiness

For TypeScript partner backends, install the adapter from npm:

npm install hive-mcp-client

The adapter is published on npm as hive-mcp-client@0.1.5; its source is mirrored in hive-intel/hive-sdk under client/. For non-TypeScript backends, use the REST fallback below.

Set the server-side secrets and run doctor:

export HIVE_API_KEY="hive_live_..."
export HIVE_SUBJECT_SIGNING_SECRET="hive_subject_..."

./node_modules/.bin/hive-mcp doctor \
  --tenant-id workspace_123 \
  --end-user-id user_456

The doctor flow checks the readiness endpoint, local subject signing, and key isolation. It does not print secrets. Add --live-subject-smoke when you want it to call a low-risk stateful tool for that subject.

You can also check readiness directly:

curl https://mcp.hiveintelligence.xyz/api/v1/b2b/readiness \
  -H "Authorization: Bearer $HIVE_API_KEY"

A B2B adapter key should report b2b_adapter_ready: true, mode: "b2b_enabled", and subject_signing_secret_configured: true. If the mode is direct_user or static_key, do not use that key for a shared partner adapter.

TypeScript adapter

Use the adapter on your server. The subject values should come from your authenticated request context.

import {
  checkHiveB2BReadiness,
  createHiveB2BAdapter,
} from "hive-mcp-client/b2b";

const readiness = await checkHiveB2BReadiness({
  apiKey: process.env.HIVE_API_KEY!,
});

if (!readiness.b2b_adapter_ready) {
  throw new Error(`Hive B2B adapter is not ready: ${readiness.mode}`);
}

const hive = await createHiveB2BAdapter({
  apiKey: process.env.HIVE_API_KEY!,
  subjectSigningSecret: process.env.HIVE_SUBJECT_SIGNING_SECRET!,
  clientName: "partner-api",
});

function subjectForCustomer(request: AuthenticatedRequest) {
  return {
    tenantId: request.workspace.id,
    endUserId: request.user.id,
  };
}

const subject = subjectForCustomer(request);

const result = await hive.createWatchlistDigestMonitor(subject, {
  name: "Daily treasury brief",
  target: {
    tokens: ["bitcoin", "ethereum"],
    wallets: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"],
  },
  cadence: "daily",
});

The B2B adapter also exposes methods for risk watches, token discovery risk, monitor listing and archival, alerts, alert acknowledgements and resolution, monitor reports, memory facts, subject-scoped clients with forSubject(), subject audit reads, and callForSubject() for lower-level tools.

Signed headers

Every subject-scoped REST or adapter call sends the Hive API key plus signed subject headers:

Authorization: Bearer <YOUR_HIVE_API_KEY>
X-Hive-Tenant-Id: <tenant-id>
X-Hive-End-User-Id: <partner-user-id>
X-Hive-Subject-Timestamp: <unix-seconds-or-iso>
X-Hive-Subject-Signature: <hmac-sha256>

The signature payload is:

METHOD + "\n" + PATH + "\n" + TENANT_ID + "\n" + END_USER_ID + "\n" + TIMESTAMP

Sign the payload with the subject signing secret using HMAC-SHA256. Reject requests where the tenant or end-user id cannot be derived from your own session.

REST fallback

Non-TypeScript partners can call REST directly after generating the signed headers on their server:

curl -X POST https://mcp.hiveintelligence.xyz/api/v1/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "X-Hive-Tenant-Id: workspace_123" \
  -H "X-Hive-End-User-Id: user_456" \
  -H "X-Hive-Subject-Timestamp: $HIVE_SUBJECT_TIMESTAMP" \
  -H "X-Hive-Subject-Signature: $HIVE_SUBJECT_SIGNATURE" \
  -d '{
    "tool": "hive_list_alerts",
    "args": {
      "limit": 10
    }
  }'

Use GET /api/v1/tools or get_api_endpoint_schema before executing a stateful tool so your request body matches the live schema.

Ship first

Start with one workflow, verify the subject audit log, then add additional monitor types.

Operational guardrails

• Keep HIVE_API_KEY and HIVE_SUBJECT_SIGNING_SECRET in server-side secret storage.
• Rotate the Hive key and subject signing secret when a partner environment is compromised.
• Use the readiness endpoint in deploy checks before enabling subject-scoped writes.
• Include monitor id, tenant id, end-user id, fetched_at, and runtime status in internal logs.
• Use subject audit events during QA to confirm no write crosses customer boundaries.
• Bound list calls with limit, cursor, or date filters when the live schema exposes them.

Related

• Stateful Monitoring
• JavaScript Integration
• Authentication
• API Integration
• Package Architecture