User Management
Every Swarmd tenant starts with a single admin user (created during tenant setup). You can invite additional team members and control exactly what each person can access using entity-level permissions.
Creating Users
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",
"permissions": [
{ "entity": "REGISTRY", "permission": "WRITE" },
{ "entity": "AGENT_CONVERSATIONS", "permission": "WRITE" },
{ "entity": "AUDIT", "permission": "READ" }
]
}'
| Field | Required | Constraints |
|---|
email | Yes | Valid email address |
password | Yes | 8–100 characters |
firstName | Yes | Max 255 characters |
lastName | Yes | Max 255 characters |
permissions | Yes | At least one permission required |
Coming soon.
Permission Model
Permissions are defined as entity:permission pairs. Each pair grants access to a specific area of the platform at a specific level.
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 |
Permission Levels
| Permission | Access level |
|---|
READ | View only |
WRITE | Create and update |
DELETE | Remove resources |
ADMIN | Full access including management operations |
Common Permission Sets
Here are permission sets for typical roles:
Agent Operator — can register agents, manage subscriptions, send messages, and handle approvals:
[
{ "entity": "REGISTRY", "permission": "WRITE" },
{ "entity": "AGENT_CONVERSATIONS", "permission": "WRITE" },
{ "entity": "AUDIT", "permission": "READ" }
]
[
{ "entity": "AUDIT", "permission": "READ" },
{ "entity": "AGENT_CONVERSATIONS", "permission": "READ" },
{ "entity": "REGISTRY", "permission": "READ" }
]
[
{ "entity": "BILLING", "permission": "ADMIN" },
{ "entity": "PAYMENT", "permission": "READ" }
]
[
{ "entity": "USERS", "permission": "ADMIN" },
{ "entity": "AGENT_CONVERSATIONS", "permission": "ADMIN" },
{ "entity": "REGISTRY", "permission": "ADMIN" },
{ "entity": "TENANT", "permission": "ADMIN" },
{ "entity": "API_KEYS", "permission": "ADMIN" },
{ "entity": "AUDIT", "permission": "ADMIN" },
{ "entity": "PAYMENT", "permission": "ADMIN" },
{ "entity": "BILLING", "permission": "ADMIN" }
]
Permissions are set at user creation time. To change a user’s permissions, you will need to delete and recreate the user.
Listing Users
curl https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/users \
-H "Authorization: Bearer $SWARMD_TOKEN"
[
{
"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" }
]
},
{
"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" }
]
}
]
Coming soon.
Getting a Specific User
curl https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/users/USER_ID \
-H "Authorization: Bearer $SWARMD_TOKEN"
Coming soon.
Removing Users
curl -X DELETE https://api.swarmd.ai/tenant-auth/v1/tenants/TENANT_ID/users/USER_ID \
-H "Authorization: Bearer $SWARMD_TOKEN"
204 No Content on success.Coming soon.
Deleting a user is permanent and cannot be undone. The user will immediately lose access to the platform.
Next Steps
