Admin User Management

Overview

Admin users are managed in a separate database from EndUsers. This API provides functionality for creating, updating, suspending, and assigning roles to Admin users who access the management console.

Required Permissions

Operation	Required Permission
Read	`admin:admin_users:read`
Write	`admin:admin_users:write`
Delete	`admin:admin_users:delete`

Endpoint List

Method	Endpoint	Description
GET	`/api/admin/admins`	List admin users
GET	`/api/admin/admins/:id`	Get admin user details
POST	`/api/admin/admins`	Create admin user
PATCH	`/api/admin/admins/:id`	Update admin user
DELETE	`/api/admin/admins/:id`	Delete admin user
POST	`/api/admin/admins/:id/suspend`	Suspend admin user
POST	`/api/admin/admins/:id/activate`	Activate admin user
POST	`/api/admin/admins/:id/unlock`	Unlock admin user
POST	`/api/admin/admins/:id/roles`	Assign role
DELETE	`/api/admin/admins/:id/roles/:roleId`	Remove role

List Admin Users

Retrieve a list of admin users.

Endpoint

GET /api/admin/admins

Query Parameters

Parameter	Type	Required	Description
`page`	integer	-	Page number (default: 1)
`limit`	integer	-	Number of items (default: 50, max: 100)
`search`	string	-	Search by email or name
`status`	string	-	Filter by status (`active`, `suspended`, `locked`)
`mfa_enabled`	boolean	-	Filter by MFA status

Request Example

curl -X GET "https://{tenant-domain}/api/admin/admins?status=active&limit=20" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "admin_abc123",
      "email": "[email protected]",
      "name": "Administrator",
      "status": "active",
      "mfa_enabled": true,
      "roles": [
        {
          "id": "role_super_admin",
          "name": "super_admin",
          "display_name": "Super Admin"
        }
      ],
      "last_login_at": 1706140800000,
      "created_at": 1705881600000
    }
  ],
  "total": 5,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}

Get Admin User Details

Retrieve detailed information for a specified admin user.

Endpoint

GET /api/admin/admins/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	✓	Admin user ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/admins/admin_abc123" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "admin_abc123",
  "email": "[email protected]",
  "name": "Administrator",
  "status": "active",
  "mfa_enabled": true,
  "mfa_method": "totp",
  "roles": [
    {
      "id": "role_super_admin",
      "name": "super_admin",
      "display_name": "Super Admin",
      "assigned_at": 1705881600000,
      "expires_at": null
    }
  ],
  "permissions": [
    "admin:admin_users:read",
    "admin:admin_users:write",
    "admin:admin_roles:read",
    "admin:admin_roles:write"
  ],
  "last_login_at": 1706140800000,
  "login_count": 150,
  "failed_login_count": 0,
  "locked_at": null,
  "created_at": 1705881600000,
  "updated_at": 1706140800000
}

Create Admin User

Create a new admin user.

Endpoint

POST /api/admin/admins

Request Body

Field	Type	Required	Description
`email`	string	✓	Email address
`name`	string	✓	Display name
`password`	string	✓	Password

Request Example

curl -X POST "https://{tenant-domain}/api/admin/admins" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "New Admin",
    "password": "SecurePassword123!"
  }'

Response Example

{
  "id": "admin_xyz789",
  "email": "[email protected]",
  "name": "New Admin",
  "status": "active",
  "mfa_enabled": false,
  "created_at": 1706227200000
}

Update Admin User

Update an existing admin user.

Endpoint

PATCH /api/admin/admins/:id

Request Body

Field	Type	Required	Description
`name`	string	-	Display name
`email`	string	-	Email address
`is_active`	boolean	-	Enable/disable

Request Example

curl -X PATCH "https://{tenant-domain}/api/admin/admins/admin_xyz789" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "email": "[email protected]"
  }'

Response Example

{
  "id": "admin_xyz789",
  "email": "[email protected]",
  "name": "Updated Name",
  "status": "active",
  "updated_at": 1706313600000
}

Delete Admin User

Delete an admin user.

Endpoint

DELETE /api/admin/admins/:id

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/admins/admin_xyz789" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "deleted": true,
  "id": "admin_xyz789"
}

Suspend Admin User

Suspend an admin user.

Endpoint

POST /api/admin/admins/:id/suspend

Request Example

curl -X POST "https://{tenant-domain}/api/admin/admins/admin_xyz789/suspend" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "admin_xyz789",
  "status": "suspended",
  "suspended_at": 1706400000000
}

Activate Admin User

Activate a suspended admin user.

Endpoint

POST /api/admin/admins/:id/activate

Request Example

curl -X POST "https://{tenant-domain}/api/admin/admins/admin_xyz789/activate" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "admin_xyz789",
  "status": "active",
  "activated_at": 1706486400000
}

Unlock Admin User

Unlock a locked admin user.

Endpoint

POST /api/admin/admins/:id/unlock

Request Example

curl -X POST "https://{tenant-domain}/api/admin/admins/admin_xyz789/unlock" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "admin_xyz789",
  "status": "active",
  "unlocked_at": 1706572800000
}

Assign Role

Assign a role to an admin user.

Endpoint

POST /api/admin/admins/:id/roles

Request Body

Field	Type	Required	Description
`role_id`	string	✓	Role ID
`expires_at`	integer	-	Expiration (Unix timestamp in milliseconds)

Request Example

curl -X POST "https://{tenant-domain}/api/admin/admins/admin_xyz789/roles" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "role_editor",
    "expires_at": 1735689600000
  }'

Response Example

{
  "admin_user_id": "admin_xyz789",
  "role_id": "role_editor",
  "assigned_at": 1706659200000,
  "expires_at": 1735689600000
}

Remove Role

Remove a role from an admin user.

Endpoint

DELETE /api/admin/admins/:id/roles/:roleId

Path Parameters

Parameter	Type	Required	Description
`id`	string	✓	Admin user ID
`roleId`	string	✓	Role ID

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/admins/admin_xyz789/roles/role_editor" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "removed": true,
  "admin_user_id": "admin_xyz789",
  "role_id": "role_editor"
}

User Status

Status	Description
`active`	Active (can login)
`suspended`	Suspended (by administrator)
`locked`	Locked (exceeded failed login attempts)

Audit Logging

All Admin user management operations are automatically recorded in the admin_audit_log table, including before/after diffs.