Manage groups to organize users and control server access in your Alpacon workspace.
List
List groups
Retrieve a paginated list of groups. Results are ordered by name by default.
Request
GET /api/iam/groups/
Query parameters
| Parameter | Type | Description |
|---|
name | string | Filter by group name (exact match) |
is_ldap_group | boolean | Filter by LDAP group status |
search | string | Search across name, display_name, tags, description, gid, server__name |
ordering | string | Sort field. Options: name, display_name, tags, gid, is_ldap_group, added_at, updated_at. Prefix with - for descending |
page | integer | Page number |
page_size | integer | Results per page (default: 15, max: 100) |
Response
{
"count": 8,
"next": null,
"previous": null,
"results": [
{
"id": "d94e1b23-5c7d-4f8a-b012-3e4f5a6b7c8d",
"name": "developers",
"display_name": "Developers",
"tags": "engineering",
"num_members": 12,
"gid": 2001,
"is_ldap_group": false,
"servers": [
"7e3984de-49ab-4cc6-bcdf-21fbd35858b8"
],
"servers_names": [
"web-server-01"
]
}
]
}
Example
curl -X GET "https://your-workspace.us1.alpacon.io/api/iam/groups/?ordering=name" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
Get
Get group
Retrieve detailed information about a specific group, including member names and timestamps.
Request
GET /api/iam/groups/{group_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
group_id | UUID | Yes | Group ID |
Response
{
"id": "d94e1b23-5c7d-4f8a-b012-3e4f5a6b7c8d",
"name": "developers",
"display_name": "Developers",
"tags": "engineering",
"num_members": 12,
"gid": 2001,
"is_ldap_group": false,
"description": "Development team with access to staging and production servers",
"servers": [
"7e3984de-49ab-4cc6-bcdf-21fbd35858b8"
],
"servers_names": [
"web-server-01"
],
"members_names": [
"admin",
"jsmith",
"developer1"
],
"added_at": "2023-06-01T08:00:00Z",
"updated_at": "2024-01-18T14:30:00Z"
}
Example
curl -X GET "https://your-workspace.us1.alpacon.io/api/iam/groups/d94e1b23-5c7d-4f8a-b012-3e4f5a6b7c8d/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
Create
Create group
Create a new group. An owner membership is automatically created for the requesting user.
Request
POST /api/iam/groups/
Request body
{
"name": "devops",
"display_name": "DevOps Team",
"tags": "infrastructure",
"description": "DevOps engineers with full server access",
"servers": [
"7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
"8f4985df-50bc-42e5-b827-32fcc46959a2"
]
}
Request parameters
| Field | Type | Required | Description |
|---|
name | string | Yes | Group name (slug format, max 128 characters, unique) |
display_name | string | Yes | Human-readable display name (max 128 characters, unique) |
tags | string | No | Comma-separated tags |
description | string | No | Group description |
is_ldap_group | boolean | No | LDAP group flag (default: false) |
servers | array[UUID] | No | Server IDs to assign to the group |
Response
{
"id": "e05f2c34-6d8e-4a9b-c123-4f5a6b7c8d9e",
"name": "devops",
"display_name": "DevOps Team",
"tags": "infrastructure",
"num_members": 1,
"gid": 2002,
"is_ldap_group": false,
"description": "DevOps engineers with full server access",
"servers": [
"7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
"8f4985df-50bc-42e5-b827-32fcc46959a2"
],
"servers_names": [
"web-server-01",
"web-server-02"
],
"members_names": [
"admin"
],
"added_at": "2024-01-20T10:00:00Z",
"updated_at": "2024-01-20T10:00:00Z"
}
Example
curl -X POST "https://your-workspace.us1.alpacon.io/api/iam/groups/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
-H "Content-Type: application/json" \
-d '{"name": "devops", "display_name": "DevOps Team", "description": "DevOps engineers with full server access"}'
Update
Update group
Update group properties. The name, gid, and id fields are read-only on update.
Request
PATCH /api/iam/groups/{group_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
group_id | UUID | Yes | Group ID |
Request body
{
"display_name": "DevOps Engineering",
"tags": "infrastructure, platform",
"description": "Updated description for DevOps team",
"servers": [
"7e3984de-49ab-4cc6-bcdf-21fbd35858b8"
]
}
Request parameters
| Field | Type | Required | Description |
|---|
display_name | string | No | Human-readable display name |
tags | string | No | Comma-separated tags |
description | string | No | Group description |
servers | array[UUID] | No | Server IDs to assign |
Response
{
"id": "e05f2c34-6d8e-4a9b-c123-4f5a6b7c8d9e",
"name": "devops",
"display_name": "DevOps Engineering",
"tags": "infrastructure, platform",
"num_members": 3,
"gid": 2002,
"is_ldap_group": false,
"description": "Updated description for DevOps team",
"servers": [
"7e3984de-49ab-4cc6-bcdf-21fbd35858b8"
],
"servers_names": [
"web-server-01"
],
"members_names": [
"admin",
"jsmith",
"developer1"
],
"added_at": "2024-01-20T10:00:00Z",
"updated_at": "2024-01-20T16:00:00Z"
}
Example
curl -X PATCH "https://your-workspace.us1.alpacon.io/api/iam/groups/e05f2c34-6d8e-4a9b-c123-4f5a6b7c8d9e/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
-H "Content-Type: application/json" \
-d '{"display_name": "DevOps Engineering"}'
Delete
Delete group
Delete a group and remove all associated memberships and server access.
Request
DELETE /api/iam/groups/{group_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
group_id | UUID | Yes | Group ID |
Response
204 No Content
Example
curl -X DELETE "https://your-workspace.us1.alpacon.io/api/iam/groups/e05f2c34-6d8e-4a9b-c123-4f5a6b7c8d9e/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
Deleting a group removes all memberships and server access associations.