Companies and Groups

Two ways to Group Registered Users.

A Company is a fixed parent - every user belonging to one customer organization shares one Company. You set this once when you create the Registered User and rarely change it.

A Group is a dynamic slice - users who match a query you define (“everyone with region = 'EU',” “everyone whose role is admin”). Membership is computed from the user’s attributes; you don’t manage a roster.

Both are optional. If you don’t pass origin_company_id and don’t set up Groups, every Registered User stands alone. That works for a single-tenant agent. For a B2B product, or any case where access should track team membership, you’ll want both.

Companies

Pass origin_company_id (your stable identifier) when you create a Registered User. Pass the same value for every user from the same customer.

1
{
2
  "origin_user_id": "user_a3f9b2",
3
  "origin_user_name": "Alice Chen",
4
  "shared_credential_group": {
5
    "origin_company_id": "company_acme",
6
    "origin_company_name": "Acme Inc."
7
  }
8
}

Two practical effects: it enables shared-credential Tool Packs (one Slack workspace per tenant, every user inherits) and it lets the dashboard filter logs, alerts, and audit by Company.

There’s no separate “create Company” endpoint. The first Registered User with a new origin_company_id creates the Company implicitly; subsequent users with the same ID join it.

For Company management endpoints (renaming, deletion, listing users in a Company), see the Companies API reference.

Groups

Groups are saved queries over Registered Users. You define them once in the dashboard at Registered Users → Groups; membership is recomputed any time a Registered User is created or updated.

Examples of useful Group definitions:

• role = "admin" - all admin users across all Companies.
• region = "EU" - for Tool Packs that should only operate in-region.
• plan = "enterprise" - for premium-tier tool access.
• team = "support" AND environment = "production" - compound queries are supported.

Group membership comes from the Registered User’s custom_groupings field. Set arbitrary key-value pairs when you create or update the user:

1
{
2
  "origin_user_id": "user_a3f9b2",
3
  "custom_groupings": {
4
    "role": "admin",
5
    "region": "EU",
6
    "plan": "enterprise"
7
  }
8
}

If you change a custom grouping, the user’s Group memberships recompute on the next request.

When Groups drive tool-pack access

For the Context layer for employees setup using SSO and SCIM, your IdP Groups sync into Agent Handler Groups automatically - every Okta or Azure AD Group becomes an Agent Handler Group, and the user’s custom_groupings get the IdP attributes attached. From there, you map each Group to a Tool Pack in the SCIM settings, and users only see the tools their Groups grant.

For Building an agent, you set custom_groupings yourself when you create or update a Registered User, and you choose Tool Packs server-side based on whatever logic fits your product.

Companies vs Groups: when to use which

In practice, most B2B agents use both - a Company per customer (fixed tenant boundary) plus a few Groups (admin vs member, region, tier).

Next

Connect your agent to Agent Handler over MCP in MCP integration.