Tenant Context

Tenant context enables B2B2C (Business-to-Business-to-Consumer) integrations. Pass tenant information with work orders to track usage, route webhooks, and attribute costs to your end users.

Understanding B2B2C

In the B2B2C model:

AgentGate is the first B (we provide the platform)
Your Platform is the second B (you build products with AgentGate)
End Users are the C (your customers use your product)

Tenant context connects actions to the end users in your platform.

What Is Tenant Context

Tenant context is metadata that travels with work orders:

{
  "taskPrompt": "...",
  "workspaceSource": { "..." },
  "tenantContext": {
    "tenantId": "acme-corp",
    "tenantUserId": "user_12345",
    "metadata": {
      "plan": "enterprise",
      "region": "us-west"
    }
  }
}

Tenant Context Fields

Field	Required	Description
`tenantId`	No	Identifier for the tenant organization
`tenantUserId`	No	Identifier for the specific user
`metadata`	No	Custom key-value pairs

All fields are optional, but providing them enables usage tracking and attribution.

Tenant ID

Identifies the organization or account in your system:

{
  "tenantId": "acme-corp"
}

Use cases:

Billing aggregation by customer
Usage limits per tenant
Tenant-specific webhooks

Tenant User ID

Identifies the specific end user:

{
  "tenantUserId": "user_12345"
}

Use cases:

Per-user usage tracking
User-level rate limiting
Audit trails

Metadata

Custom information for your use:

{
  "metadata": {
    "plan": "enterprise",
    "department": "engineering",
    "costCenter": "CC-1234",
    "projectId": "proj_abc"
  }
}

Metadata is passed through to webhooks and available in usage reports.

Passing Tenant Context

Include tenant context when creating work orders:

const workOrder = await client.workOrders.create({
  taskPrompt: "Add unit tests for the user service",
  workspaceSource: {
    type: "git",
    repository: "https://github.com/acme/app"
  },
  tenantContext: {
    tenantId: "acme-corp",
    tenantUserId: "user_12345",
    metadata: {
      requestId: "req_abc123"
    }
  }
});

curl -X POST https://agentgate.mynewapi.com/v1/work-orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskPrompt": "Add unit tests for the user service",
    "workspaceSource": {
      "type": "git",
      "repository": "https://github.com/acme/app"
    },
    "tenantContext": {
      "tenantId": "acme-corp",
      "tenantUserId": "user_12345",
      "metadata": {
        "requestId": "req_abc123"
      }
    }
  }'

Tenant Context in Webhooks

Webhooks include tenant context, enabling you to route notifications:

{
  "type": "run.completed",
  "data": {
    "runId": "run_abc123",
    "status": "succeeded",
    "tenantContext": {
      "tenantId": "acme-corp",
      "tenantUserId": "user_12345",
      "metadata": {
        "requestId": "req_abc123"
      }
    }
  }
}

Webhook Routing

Use tenant context to route webhooks to tenant-specific endpoints:

app.post('/webhooks/agentgate', (req, res) => {
  const { tenantContext, ...event } = req.body.data;

  // Route to tenant-specific handler
  const tenantEndpoint = getTenantEndpoint(tenantContext.tenantId);
  forwardToTenant(tenantEndpoint, event);

  res.sendStatus(200);
});

Usage Attribution

Tenant context enables usage tracking and billing:

Query Usage by Tenant

curl "https://agentgate.mynewapi.com/v1/credits/usage?tenantId=acme-corp" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "transactions": [
    {
      "type": "deduction",
      "amount": 150,
      "runId": "run_abc123",
      "tenantId": "acme-corp",
      "tenantUserId": "user_12345",
      "createdAt": "2024-01-15T10:35:00Z"
    }
  ],
  "total": 1500,
  "period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  }
}

Billing Integration

Use usage data to bill your customers:

// Get usage for billing period
const usage = await client.credits.getUsage({
  tenantId: 'acme-corp',
  startDate: billingPeriodStart,
  endDate: billingPeriodEnd
});

// Calculate cost with your margin
const cost = usage.total * creditPriceCents * (1 + marginPercent);

// Create invoice in your billing system
await billingSystem.createInvoice({
  customerId: 'acme-corp',
  amount: cost,
  description: 'AgentGate usage'
});

Best Practices

Consistent Tenant IDs

Use consistent, stable identifiers:

Good Examples

// Database IDs
{ "tenantId": "org_12345" }

// Slugs
{ "tenantId": "acme-corp" }

// UUIDs
{ "tenantId": "550e8400-e29b-41d4-a716-446655440000" }

Avoid

// Mutable values
{ "tenantId": "Acme Corporation" }  // Names change

// Email addresses
{ "tenantId": "admin@acme.com" }  // People leave

// Temporary values
{ "tenantId": "trial_123" }  // Status changes

Metadata Guidelines

Include useful context in metadata:

{
  "metadata": {
    // Billing context
    "costCenter": "engineering",
    "budgetCode": "AI-2024",

    // Request context
    "requestId": "req_abc123",
    "triggeredBy": "ci-pipeline",

    // Feature context
    "feature": "code-review",
    "environment": "production"
  }
}

Privacy Considerations

Don’t include personally identifiable information (PII) in tenant context unless necessary. Use opaque identifiers when possible.

Credits

Track and manage credit usage

Webhooks

Receive tenant-aware notifications

​Tenant Context

​Understanding B2B2C

​What Is Tenant Context

​Tenant Context Fields

​Tenant ID

​Tenant User ID

​Metadata

​Passing Tenant Context

​Tenant Context in Webhooks

​Webhook Routing

​Usage Attribution

​Query Usage by Tenant

​Billing Integration

​Best Practices

​Consistent Tenant IDs

​Metadata Guidelines

​Privacy Considerations

​Related

Credits

Webhooks

Tenant Context

Understanding B2B2C

What Is Tenant Context

Tenant Context Fields

Tenant ID

Tenant User ID

Metadata

Passing Tenant Context

Tenant Context in Webhooks

Webhook Routing

Usage Attribution

Query Usage by Tenant

Billing Integration

Best Practices

Consistent Tenant IDs

Metadata Guidelines

Privacy Considerations

Related