Manage user accounts in your Alpacon workspace. Use pk=- in place of a user ID to refer to the currently authenticated user.
List
List users
Retrieve a paginated list of users. Results are ordered by superuser status first, then staff, then active, then by username.
Request
GET /api/iam/users/
Query parameters
| Parameter | Type | Description |
|---|
is_active | boolean | Filter by active status |
is_staff | boolean | Filter by staff status |
is_superuser | boolean | Filter by superuser status |
is_ldap_user | boolean | Filter by LDAP user status |
shell | string | Filter by shell (exact match) |
username | string | Filter by username (exact match) |
username__icontains | string | Filter by username (case-insensitive partial match) |
added_at__gte | datetime | Filter users added on or after this date |
added_at__lte | datetime | Filter users added on or before this date |
added_at__gt | datetime | Filter users added after this date |
added_at__lt | datetime | Filter users added before this date |
exclude_group | UUID | Exclude users who belong to this group |
search | string | Search across username, first_name, last_name, email, phone, tags, description, uid, added_at |
ordering | string | Sort field. Options: first_name, last_name, email, tags, uid, is_superuser, is_staff, is_active, date_joined, last_login, added_at, updated_at. Prefix with - for descending |
page | integer | Page number |
page_size | integer | Results per page (default: 15, max: 100) |
Response
{
"count": 15,
"next": null,
"previous": null,
"results": [
{
"id": "a540bf0f-8b37-4f03-8546-dd71c6b03329",
"auth0_id": "auth0|64a1b2c3d4e5f6a7b8c9d0e1",
"username": "admin",
"first_name": "John",
"last_name": "Doe",
"email": "admin@example.com",
"phone": "+1-555-0100",
"tags": "infrastructure, lead",
"num_groups": 3,
"uid": 2000,
"is_active": true,
"is_staff": true,
"is_superuser": true,
"is_ldap_user": false,
"date_joined": "2023-01-15T10:00:00Z"
}
]
}
Example
curl -X GET "https://your-workspace.us1.alpacon.io/api/iam/users/?is_active=true&ordering=-date_joined" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
Get
Get user
Retrieve detailed information about a specific user. Use pk=- to retrieve the currently authenticated user.
Request
GET /api/iam/users/{user_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
user_id | UUID | Yes | User ID, or - for the authenticated user |
Response
{
"id": "a540bf0f-8b37-4f03-8546-dd71c6b03329",
"auth0_id": "auth0|64a1b2c3d4e5f6a7b8c9d0e1",
"username": "admin",
"first_name": "John",
"last_name": "Doe",
"email": "admin@example.com",
"phone": "+1-555-0100",
"tags": "infrastructure, lead",
"num_groups": 3,
"uid": 2000,
"is_active": true,
"is_staff": true,
"is_superuser": true,
"is_ldap_user": false,
"date_joined": "2023-01-15T10:00:00Z",
"description": "System administrator",
"shell": "/bin/bash",
"home_directory": "/home/admin",
"last_login": "2024-01-20T09:15:00Z",
"last_login_ip": "203.0.113.45",
"added_at": "2023-01-15T10:00:00Z",
"updated_at": "2024-01-20T09:15:00Z",
"websh_total_lifetime": 86400,
"webftp_upload_bytes": 1048576,
"webftp_download_bytes": 5242880
}
Example
curl -X GET "https://your-workspace.us1.alpacon.io/api/iam/users/a540bf0f-8b37-4f03-8546-dd71c6b03329/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
Create
Create user
Create a new user account. The uid is auto-assigned starting at 2000 and home_directory is set to /home/{username}. If password is not provided, one is auto-generated.
Request
POST /api/iam/users/
Request body
{
"username": "jsmith",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane.smith@example.com",
"phone": "+1-555-0200",
"tags": "developer",
"description": "Backend developer",
"shell": "/bin/bash",
"is_active": true,
"is_staff": false,
"is_superuser": false,
"is_ldap_user": false
}
Request parameters
| Field | Type | Required | Description |
|---|
username | string | Yes | Username. Must match ^[a-z][a-z0-9_-]*$ |
first_name | string | No | First name |
last_name | string | No | Last name |
email | string | No | Email address |
phone | string | No | Phone number |
tags | string | No | Comma-separated tags |
description | string | No | User description |
shell | string | No | Login shell (default: /bin/bash) |
is_active | boolean | No | Active status (default: true) |
is_staff | boolean | No | Staff status (default: false) |
is_superuser | boolean | No | Superuser status (default: false) |
is_ldap_user | boolean | No | LDAP user flag (default: false) |
Response
{
"id": "b651cf10-9c48-4a14-9657-ee82d7c14430",
"auth0_id": "",
"username": "jsmith",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane.smith@example.com",
"phone": "+1-555-0200",
"tags": "developer",
"num_groups": 0,
"uid": 2001,
"is_active": true,
"is_staff": false,
"is_superuser": false,
"is_ldap_user": false,
"date_joined": "2024-01-20T10:00:00Z"
}
Example
curl -X POST "https://your-workspace.us1.alpacon.io/api/iam/users/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
-H "Content-Type: application/json" \
-d '{"username": "jsmith", "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com"}'
Update
Update user
Update user account properties. Only staff users can update other users. The username field is read-only on update.
Request
PATCH /api/iam/users/{user_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
user_id | UUID | Yes | User ID |
Request body
{
"first_name": "Janet",
"email": "janet.smith@example.com",
"tags": "developer, senior",
"is_active": true,
"is_staff": true
}
Request parameters
| Field | Type | Required | Description |
|---|
first_name | string | No | First name |
last_name | string | No | Last name |
email | string | No | Email address |
phone | string | No | Phone number |
tags | string | No | Comma-separated tags |
description | string | No | User description |
shell | string | No | Login shell |
is_active | boolean | No | Active status |
is_staff | boolean | No | Staff status |
password | string | No | New password (write-only) |
Response
{
"id": "b651cf10-9c48-4a14-9657-ee82d7c14430",
"auth0_id": "",
"username": "jsmith",
"first_name": "Janet",
"last_name": "Smith",
"email": "janet.smith@example.com",
"phone": "+1-555-0200",
"tags": "developer, senior",
"num_groups": 1,
"uid": 2001,
"is_active": true,
"is_staff": true,
"is_superuser": false,
"is_ldap_user": false,
"date_joined": "2024-01-20T10:00:00Z"
}
Example
curl -X PATCH "https://your-workspace.us1.alpacon.io/api/iam/users/b651cf10-9c48-4a14-9657-ee82d7c14430/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
-H "Content-Type: application/json" \
-d '{"first_name": "Janet", "is_staff": true}'
Delete
Delete user
Delete a user account. The API validates that the user is not the last superuser, not the last owner of any group, and not a billing owner. Use ?purge=true to permanently purge the user record.
Request
DELETE /api/iam/users/{user_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
user_id | UUID | Yes | User ID |
Query parameters
| Parameter | Type | Description |
|---|
purge | boolean | Set to true to permanently purge the user record |
Response
204 No Content
Example
curl -X DELETE "https://your-workspace.us1.alpacon.io/api/iam/users/b651cf10-9c48-4a14-9657-ee82d7c14430/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
Deleting a user removes their account and all associated group memberships. The operation will fail if the user is the last superuser, the last owner of any group, or a billing owner.