Manage group memberships to control user roles and access within groups.
List
List memberships
Retrieve a paginated list of group memberships. Results are ordered by role then by last updated time by default.
Request
GET /api/iam/memberships/
Query parameters
| Parameter | Type | Description |
|---|
group | UUID | Filter by group ID |
user | UUID | Filter by user ID |
role | string | Filter by role (member, manager, owner) |
search | string | Search across id, role, group__name, group__display_name, user__username, user__email |
ordering | string | Sort field. Options: role, added_at, updated_at. Prefix with - for descending |
page | integer | Page number |
page_size | integer | Results per page (default: 15, max: 100) |
Response
{
"count": 12,
"next": null,
"previous": null,
"results": [
{
"id": "f16a3d45-7e9f-4b0c-d234-5a6b7c8d9e0f",
"group": "d94e1b23-5c7d-4f8a-b012-3e4f5a6b7c8d",
"group_name": "developers",
"user": {
"id": "a540bf0f-8b37-4f03-8546-dd71c6b03329",
"name": "admin",
"email": "admin@example.com",
"username": "admin",
"is_active": true,
"is_staff": true,
"is_superuser": true
},
"role": "owner"
}
]
}
Example
curl -X GET "https://your-workspace.us1.alpacon.io/api/iam/memberships/?group=d94e1b23-5c7d-4f8a-b012-3e4f5a6b7c8d" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
Create
Create membership
Add a user to a group with a specified role. You cannot add members to the default “alpacon” group through this endpoint.
Request
POST /api/iam/memberships/
Request body
{
"group": "d94e1b23-5c7d-4f8a-b012-3e4f5a6b7c8d",
"user": "b651cf10-9c48-4a14-9657-ee82d7c14430",
"role": "member"
}
Request parameters
| Field | Type | Required | Description |
|---|
group | UUID | Yes | Group ID (cannot be the default “alpacon” group) |
user | UUID | Yes | User ID. Also accepts {"id": "uuid"} object format |
role | string | No | Role: member, manager, or owner (default: member) |
Role hierarchy
| Role | Description |
|---|
member | Default role, can be removed by managers or owners |
manager | Can add/remove members and update group settings |
owner | Full control, at least one owner per group is enforced |
Response
{
"id": "a27b4e56-8f0a-4c1d-e345-6b7c8d9e0f1a",
"group": "d94e1b23-5c7d-4f8a-b012-3e4f5a6b7c8d",
"group_name": "developers",
"user": {
"id": "b651cf10-9c48-4a14-9657-ee82d7c14430",
"name": "jsmith",
"email": "jane.smith@example.com",
"username": "jsmith",
"is_active": true,
"is_staff": false,
"is_superuser": false
},
"role": "member"
}
Example
curl -X POST "https://your-workspace.us1.alpacon.io/api/iam/memberships/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
-H "Content-Type: application/json" \
-d '{"group": "d94e1b23-5c7d-4f8a-b012-3e4f5a6b7c8d", "user": "b651cf10-9c48-4a14-9657-ee82d7c14430", "role": "member"}'
Update
Update membership
Change a user’s role within a group. Only the role field is writable.
Request
PATCH /api/iam/memberships/{membership_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
membership_id | UUID | Yes | Membership ID |
Request body
{
"role": "manager"
}
Request parameters
| Field | Type | Required | Description |
|---|
role | string | No | New role: member, manager, or owner |
Response
{
"id": "a27b4e56-8f0a-4c1d-e345-6b7c8d9e0f1a",
"group": "d94e1b23-5c7d-4f8a-b012-3e4f5a6b7c8d",
"group_name": "developers",
"user": {
"id": "b651cf10-9c48-4a14-9657-ee82d7c14430",
"name": "jsmith",
"email": "jane.smith@example.com",
"username": "jsmith",
"is_active": true,
"is_staff": false,
"is_superuser": false
},
"role": "manager"
}
Example
curl -X PATCH "https://your-workspace.us1.alpacon.io/api/iam/memberships/a27b4e56-8f0a-4c1d-e345-6b7c8d9e0f1a/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
-H "Content-Type: application/json" \
-d '{"role": "manager"}'
Delete
Delete membership
Remove a user from a group. A group must always have at least one owner. Attempting to remove the last owner returns a USER_UNIQUE_GROUP_OWNER error.
Request
DELETE /api/iam/memberships/{membership_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
membership_id | UUID | Yes | Membership ID |
Response
204 No Content
Example
curl -X DELETE "https://your-workspace.us1.alpacon.io/api/iam/memberships/a27b4e56-8f0a-4c1d-e345-6b7c8d9e0f1a/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
A group must always have at least one owner. Removing the last owner will return an error.