> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarmd.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# User Management

> Invite team members to your tenant, manage groups, and control access through group-based permissions.

# User Management

Every Swarmd tenant starts with a single admin user (created during tenant setup) who is automatically placed in the **Tenant Administrator** group. You can invite additional team members and control what they can access by assigning them to groups.

***

## Groups

Permissions in Swarmd are managed exclusively through groups. Every tenant is created with four default groups:

| Group                    | Purpose                                                                       | Default |
| ------------------------ | ----------------------------------------------------------------------------- | ------- |
| **Tenant Administrator** | Full access to all tenant resources including group and user management       | No      |
| **Editor**               | Day-to-day operations — manage agents, conversations, approvals, and API keys | No      |
| **Viewer**               | Read-only access to agents, conversations, approvals, and audit logs          | Yes     |
| **Billing Manager**      | Manage billing and payment settings                                           | No      |

The **Viewer** group is marked as the default — users created without explicit group assignment are automatically added to it.

You can also create custom groups with any combination of permissions to match your team's needs.

***

## Creating Users

When creating a user, specify which groups they should belong to via `groupIds`. If omitted, the user is assigned to the default group (Viewer).

<Tabs>
  <Tab title="API">
    Invite a user into the Editor group:

    ```bash theme={null}
    # First, list groups to get the Editor group ID
    curl https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/groups \
      -H "Authorization: Bearer $SWARMD_TOKEN"

    # Then create the user with that group ID
    curl -X POST https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/users \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SWARMD_TOKEN" \
      -d '{
        "email": "engineer@acme.com",
        "password": "initial-password",
        "firstName": "Alex",
        "lastName": "Chen",
        "groupIds": ["EDITOR_GROUP_ID"]
      }'
    ```

    Invite a user into multiple groups:

    ```bash theme={null}
    curl -X POST https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/users \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SWARMD_TOKEN" \
      -d '{
        "email": "lead@acme.com",
        "password": "initial-password",
        "firstName": "Jordan",
        "lastName": "Lee",
        "groupIds": ["EDITOR_GROUP_ID", "BILLING_MANAGER_GROUP_ID"]
      }'
    ```

    Invite a user with defaults (Viewer group):

    ```bash theme={null}
    curl -X POST https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/users \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SWARMD_TOKEN" \
      -d '{
        "email": "observer@acme.com",
        "password": "initial-password",
        "firstName": "Sam",
        "lastName": "Taylor"
      }'
    ```

    | Field       | Required | Constraints                                                   |
    | ----------- | -------- | ------------------------------------------------------------- |
    | `email`     | Yes      | Valid email address                                           |
    | `password`  | Yes      | 8-100 characters                                              |
    | `firstName` | Yes      | Max 255 characters                                            |
    | `lastName`  | Yes      | Max 255 characters                                            |
    | `groupIds`  | No       | List of group UUIDs. Defaults to the Viewer group if omitted. |
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

***

## Managing Group Membership

You can add or remove users from groups at any time. Permission changes take effect on the user's next login.

<Tabs>
  <Tab title="API">
    Add a user to a group:

    ```bash theme={null}
    curl -X POST https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/groups/GROUP_ID/members/USER_ID \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```

    Remove a user from a group:

    ```bash theme={null}
    curl -X DELETE https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/groups/GROUP_ID/members/USER_ID \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

***

## Permission Model

A user's effective permissions are the union of all permissions from all groups they belong to. For example, a user in both **Editor** and **Billing Manager** gets the combined permissions of both groups.

### Entity Types

| Entity                | What it controls                                         |
| --------------------- | -------------------------------------------------------- |
| `USERS`               | Managing users within the tenant                         |
| `AGENT_CONVERSATIONS` | Sending messages, viewing tasks, managing HITL approvals |
| `REGISTRY`            | Registering agents, managing subscriptions               |
| `TENANT`              | Tenant-level settings and configuration                  |
| `API_KEYS`            | Managing API keys                                        |
| `AUDIT`               | Viewing audit events and traces                          |
| `PAYMENT`             | Viewing payment history                                  |
| `BILLING`             | Managing billing accounts and subscriptions              |
| `HITL_REQUESTS`       | Managing human-in-the-loop approval requests             |
| `GROUPS`              | Managing groups and group membership                     |

### Permission Levels

| Permission | Access level                                |
| ---------- | ------------------------------------------- |
| `READ`     | View only                                   |
| `WRITE`    | Create and update                           |
| `DELETE`   | Remove resources                            |
| `ADMIN`    | Full access including management operations |

### Default Group Permissions

**Tenant Administrator** — all entity types with all permission levels (40 permissions).

**Editor** — `REGISTRY:*`, `AGENT_CONVERSATIONS:*`, `HITL_REQUESTS:*`, `API_KEYS:READ/WRITE`, `AUDIT:READ`, `GROUPS:READ`.

**Viewer** — `REGISTRY:READ`, `AGENT_CONVERSATIONS:READ`, `HITL_REQUESTS:READ`, `AUDIT:READ`.

**Billing Manager** — `BILLING:*`, `PAYMENT:*`, `TENANT:READ`.

***

## Creating Custom Groups

You can create custom groups with any combination of permissions.

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    curl -X POST https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/groups \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SWARMD_TOKEN" \
      -d '{
        "name": "Agent Operator",
        "description": "Can manage agents and view audit logs",
        "isDefault": false,
        "permissions": [
          { "entity": "REGISTRY", "permission": "WRITE" },
          { "entity": "AGENT_CONVERSATIONS", "permission": "WRITE" },
          { "entity": "AUDIT", "permission": "READ" }
        ]
      }'
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

Updating a group creates a new immutable version — the previous version is preserved for audit purposes. All members of the group receive the updated permissions on their next login.

***

## Viewing Your Own Permissions

Any authenticated user can call the `/v1/me` endpoint to see their identity, group memberships, and effective permissions:

```bash theme={null}
curl https://api.swarmd.ai/tenant-auth/v1/me \
  -H "Authorization: Bearer $SWARMD_TOKEN"
```

Response:

```json theme={null}
{
  "userId": "user-uuid",
  "tenantId": "tenant-uuid",
  "email": "engineer@acme.com",
  "firstName": "Alex",
  "lastName": "Chen",
  "groups": [
    {
      "id": "group-uuid",
      "name": "Editor",
      "description": "Manage agents, conversations, and approvals",
      "version": 1,
      "permissions": [
        { "entity": "REGISTRY", "permission": "READ" },
        { "entity": "REGISTRY", "permission": "WRITE" }
      ]
    }
  ],
  "permissions": [
    { "entity": "REGISTRY", "permission": "READ" },
    { "entity": "REGISTRY", "permission": "WRITE" },
    { "entity": "AGENT_CONVERSATIONS", "permission": "READ" },
    { "entity": "AGENT_CONVERSATIONS", "permission": "WRITE" }
  ]
}
```

***

## Listing Users

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    curl https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/users \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```

    Response:

    ```json theme={null}
    [
      {
        "id": "user-uuid-1",
        "tenantId": "tenant-uuid",
        "email": "admin@acme.com",
        "firstName": "Jane",
        "lastName": "Smith",
        "createdAt": "2025-01-15T10:00:00",
        "permissions": [
          { "entity": "USERS", "permission": "ADMIN" },
          { "entity": "REGISTRY", "permission": "ADMIN" },
          { "entity": "GROUPS", "permission": "ADMIN" }
        ],
        "groupIds": ["tenant-admin-group-uuid"]
      },
      {
        "id": "user-uuid-2",
        "tenantId": "tenant-uuid",
        "email": "engineer@acme.com",
        "firstName": "Alex",
        "lastName": "Chen",
        "createdAt": "2025-03-10T14:00:00",
        "permissions": [
          { "entity": "REGISTRY", "permission": "WRITE" },
          { "entity": "AGENT_CONVERSATIONS", "permission": "WRITE" }
        ],
        "groupIds": ["editor-group-uuid"]
      }
    ]
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

***

## Getting a Specific User

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    curl https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/users/USER_ID \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

***

## Removing Users

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    curl -X DELETE https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/users/USER_ID \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```

    Returns `204 No Content` on success.
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

<Warning>
  Deleting a user is permanent and cannot be undone. The user will immediately lose access to the platform.
</Warning>

***

## Audit Trail

Every group change and membership change is recorded:

* **Group versions** — each update to a group's name, description, or permissions creates a new immutable version. View the history with `GET /v1/tenants/TENANT_ID/groups/GROUP_ID/versions`.
* **Membership events** — every group assignment and removal is logged with who performed the action and when.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Monitoring & Audit" icon="chart-line" href="/tutorials/monitoring-and-audit">
    Track user actions and agent activity in the audit log.
  </Card>

  <Card title="Agent Discovery" icon="magnifying-glass" href="/tutorials/agent-discovery">
    Make your agents discoverable on the marketplace.
  </Card>
</CardGroup>