> 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.

# Team and roles

> How to invite dashboard members, assign default or custom roles, and choose the right permission split for your team.

This is for inviting *your team* to the Agent Handler dashboard - engineers, security, ops. Not for your end users (those are [Registered Users](/merge-agent-handler/build/users/registered-users), an entirely separate concept).

Members get a role. Roles map to a permission set. Four default roles cover most teams; custom roles cover the rest.

## Inviting a member

From [Settings → Organization](https://ah.merge.dev/settings/organization), click **Invite member**, enter their email, pick a role, send. They get an email with a link; clicking it lands them in the dashboard with the role you assigned.

If your org requires SSO or SCIM, members get provisioned through your IdP instead - see [Single sign-on](/merge-agent-handler/administer/sso) and [SCIM provisioning](/merge-agent-handler/administer/scim).

## Default roles

| Role          | What they can do                                                                                                                           |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Admin**     | Full access. User management, billing, API keys, SSO/SCIM config, custom roles, all read/write across the platform.                        |
| **Developer** | Manage Tool Packs, Connectors, security rules, and webhooks. View API keys, logs, alerts. Cannot manage members, billing, or org settings. |
| **Security**  | Manage security rules, custom regex, alerts, and audit log. View Tool Packs and Connectors. Cannot edit Tool Packs or Connectors directly. |
| **Read-Only** | View everything, change nothing. Useful for auditors, support, executives.                                                                 |

## Picking the right split

* **Startup, small team.** Everyone is Admin. Move people off Admin once you have someone owning security or billing.
* **Mid-size, separated security.** Engineers as Developer, security or compliance lead as Security, founders/leads as Admin. The most common pattern.
* **Large org, full RBAC.** Add custom roles for your specific shapes - "Connector ops" can manage Connectors but not Tool Packs; "Auditor" gets read-only on logs and Audit Trail.

Don't default everyone to Admin. Admin can rotate API keys and remove other members, both hard to recover from.

## Custom roles

When the defaults don't fit, define a custom role. Example shapes that come up often:

* **Tool Pack owner.** Edit Tool Packs, view Registered Users, no security or billing access.
* **Compliance officer.** Read everything, edit security rules, no tool-pack edits, no member management.
* **On-call.** View logs and alerts, no other access.

To create one:

1. Open [Settings → Roles](https://ah.merge.dev/settings/roles).
2. Click **Add custom role**.
3. Name it.
4. Toggle the specific permissions you want. Each permission shows what surface it grants - read or write, on which resource type.
5. Save.

The role is now assignable to members. Permissions on existing members aren't changed retroactively; you have to assign the new role from the member's profile.

## When members leave

Two paths:

* **Just remove them.** Their dashboard access ends immediately. They can be re-invited later if they come back.
* **Convert to read-only first, then remove.** Useful in regulated environments where you want a paper trail before revoking - change their role to Read-Only, document the change in the [Audit Trail](/merge-agent-handler/observe/audit-trail), then remove a few days later.

If they were the only Admin, promote someone else first. The dashboard requires at least one Admin.

## Next

Authenticate members through your IdP with [Single sign-on](/merge-agent-handler/administer/sso).