Memberships
Endpoint: /api/iam/memberships/
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\""Error responses
| Status | Error code | Description |
|---|---|---|
| 400 | — | Invalid parameters (e.g. role isn’t a valid choice) |
| 400 | user_unique_group_owner | Cannot remove or demote the last owner of a group |
| 400 | group_default_group | Cannot update or delete a membership in the default alpacon group |
| 401 | — | Not authenticated. Uncoded {"detail": "..."} response |
| 403 | membership_privilege_required | Caller’s role in this group isn’t high enough to create or remove this membership |
| 403 | membership_group_owner_required | Updating this membership requires the caller to be an owner of the group |
| 403 | rbac_permission_required | Caller’s role grants no membership:<action> permission at all |
| 404 | — | Membership not found. Uncoded {"detail": "..."} response |