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

Invite a user into the Editor group:

# 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:

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):

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.

Managing Group Membership

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

Add a user to a group:

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:

curl -X DELETE https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/groups/GROUP_ID/members/USER_ID \
  -H "Authorization: Bearer $SWARMD_TOKEN"

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.

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" }
    ]
  }'

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:

curl https://api.swarmd.ai/tenant-auth/v1/me \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Response:

{
  "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

curl https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/users \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Response:

[
  {
    "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"]
  }
]

Getting a Specific User

curl https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/users/USER_ID \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Removing Users

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.

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

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.

Getting Started

Platform Management

User Management

User Management

Groups

Creating Users

Managing Group Membership

Permission Model

Entity Types

Permission Levels

Default Group Permissions

Creating Custom Groups

Viewing Your Own Permissions

Listing Users

Getting a Specific User

Removing Users

Audit Trail

Next Steps

Monitoring & Audit

Agent Discovery

Getting Started

Platform Management

Documentation Index

​User Management

​Groups

​Creating Users

​Managing Group Membership

​Permission Model

​Entity Types

​Permission Levels

​Default Group Permissions

​Creating Custom Groups

​Viewing Your Own Permissions

​Listing Users

​Getting a Specific User

​Removing Users

​Audit Trail

​Next Steps

Monitoring & Audit

Agent Discovery

User Management

Groups

Creating Users

Managing Group Membership

Permission Model

Entity Types

Permission Levels

Default Group Permissions

Creating Custom Groups

Viewing Your Own Permissions

Listing Users

Getting a Specific User

Removing Users

Audit Trail

Next Steps