> This page is for Agent Handler.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Companies and Groups

> How to model B2B tenants with Companies and slice users dynamically with Groups in Agent Handler.

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.

```json
{
  "origin_user_id": "user_a3f9b2",
  "origin_user_name": "Alice Chen",
  "shared_credential_group": {
    "origin_company_id": "company_acme",
    "origin_company_name": "Acme Inc."
  }
}
```

Two practical effects: it enables [shared-credential Tool Packs](/merge-agent-handler/build/tools/tool-packs#individual-vs-shared-credential-scope) (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](/merge-agent-handler/agent-handler/registered-users) reference.

## Groups

Groups are saved queries over Registered Users. You define them once in the dashboard at [Registered Users → Groups](https://ah.merge.dev/registered-users/groupings); 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:

```json
{
  "origin_user_id": "user_a3f9b2",
  "custom_groupings": {
    "role": "admin",
    "region": "EU",
    "plan": "enterprise"
  }
}
```

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

### When Groups drive tool-pack access

For the [Agent Handler for Employees](/merge-agent-handler/setup/agent-handler-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

| Question                                                | Use a Company             | Use a Group |
| ------------------------------------------------------- | ------------------------- | ----------- |
| Does every user from one customer always belong here?   | Yes                       | No          |
| Should it drive shared-credential scope?                | Yes                       | No          |
| Is membership dynamic, based on attributes?             | No                        | Yes         |
| Do users belong to more than one of these at once?      | No (one Company per user) | Yes         |
| Does it map cleanly to your customer's `tenants` table? | Yes                       | No          |

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](/merge-agent-handler/build/connecting-agents/mcp-integration).