Users API

The Users API manages user accounts, permissions, and profile information for the Alaikis AI platform.

Overview

The Users API provides:

• User account management (CRUD operations)
• Role and permission management
• User profile management
• Team and organization management
• Activity and audit logs

Endpoints

Get Current User

Retrieve information about the authenticated user.

Endpoint:

GET /users/me

Response:

{
  "success": true,
  "data": {
    "user_id": "usr_abc123xyz",
    "email": "developer@example.com",
    "name": "API Developer",
    "role": "developer",
    "organization": {
      "org_id": "org_xyz789",
      "name": "Example Corp",
      "plan": "professional"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "last_login": "2024-05-14T06:30:00Z",
    "email_verified": true,
    "mfa_enabled": false,
    "api_usage": {
      "this_month": 12450,
      "limit": 100000,
      "remaining": 87550
    }
  },
  "meta": {
    "request_id": "req_me_abc123",
    "processing_time_ms": 18
  }
}

---

List Users

List all users in your organization (admin only).

Endpoint:

GET /users

Query Parameters:

Parameter	Type	Description
limit	integer	Results per page (default 20)
offset	integer	Pagination offset
role	string	Filter by role
search	string	Search by name or email

Response:

{
  "success": true,
  "data": {
    "users": [
      {
        "user_id": "usr_abc123xyz",
        "email": "admin@example.com",
        "name": "Admin User",
        "role": "admin",
        "created_at": "2024-01-10T08:00:00Z",
        "last_login": "2024-05-14T06:30:00Z",
        "status": "active"
      },
      {
        "user_id": "usr_def456uvw",
        "email": "developer@example.com",
        "name": "API Developer",
        "role": "developer",
        "created_at": "2024-01-15T10:30:00Z",
        "last_login": "2024-05-14T05:00:00Z",
        "status": "active"
      }
    ],
    "total": 15,
    "limit": 20,
    "offset": 0
  },
  "meta": {
    "request_id": "req_list_xyz789",
    "processing_time_ms": 35
  }
}

---

Get User by ID

Retrieve a specific user's details.

Endpoint:

GET /users/{user_id}

Response:

{
  "success": true,
  "data": {
    "user_id": "usr_abc123xyz",
    "email": "developer@example.com",
    "name": "API Developer",
    "role": "developer",
    "organization_id": "org_xyz789",
    "created_at": "2024-01-15T10:30:00Z",
    "last_login": "2024-05-14T06:30:00Z",
    "email_verified": true,
    "status": "active",
    "permissions": [
      "packing:read",
      "packing:write",
      "product-trace:full"
    ],
    "teams": [
      {
        "team_id": "team_logistics",
        "name": "Logistics Team"
      }
    ]
  },
  "meta": {
    "request_id": "req_user_456",
    "processing_time_ms": 27
  }
}

---

Create User

Create a new user in your organization (admin only).

Endpoint:

POST /users

Request Body:

{
  "email": "new.user@example.com",
  "name": "New User",
  "role": "developer",
  "password": "SecurePassword123!",
  "send_invite": true,
  "teams": ["team_logistics"],
  "permissions": ["packing:read", "packing:write"]
}

Response:

{
  "success": true,
  "data": {
    "user_id": "usr_new_123abc",
    "email": "new.user@example.com",
    "name": "New User",
    "role": "developer",
    "created_at": "2024-05-14T10:00:00Z",
    "status": "pending_verification",
    "invite_sent": true
  },
  "meta": {
    "request_id": "req_create_789",
    "processing_time_ms": 89
  }
}

---

Update User

Update user information (admin only or self-update).

Endpoint:

PATCH /users/{user_id}

Request Body:

{
  "name": "Updated Name",
  "role": "admin",
  "permissions": ["packing:full", "product-trace:full"],
  "teams": ["team_logistics", "team_analytics"]
}

---

Delete User

Delete a user account (admin only).

Endpoint:

DELETE /users/{user_id}

Response:

{
  "success": true,
  "data": {
    "user_id": "usr_abc123xyz",
    "deleted_at": "2024-05-14T11:00:00Z",
    "message": "User successfully deleted"
  },
  "meta": {
    "request_id": "req_delete_abc",
    "processing_time_ms": 42
  }
}

---

Get User Activity Log

Retrieve user activity audit log.

Endpoint:

GET /users/{user_id}/activity

Query Parameters:

Parameter	Type	Description
limit	integer	Results per page (default 50)
offset	integer	Pagination offset
start_date	string	Filter start date
end_date	string	Filter end date
action_type	string	Filter by action type

Response:

{
  "success": true,
  "data": {
    "activities": [
      {
        "timestamp": "2024-05-14T08:45:12Z",
        "action": "api_request",
        "endpoint": "/packing/calculate",
        "method": "POST",
        "ip_address": "192.168.1.1",
        "user_agent": "Alaikis Python SDK v1.2.0",
        "success": true,
        "response_time_ms": 156
      }
    ],
    "total": 1542
  },
  "meta": {
    "request_id": "req_activity_xyz",
    "processing_time_ms": 63
  }
}

---

User Roles

Role	Description	Permissions
owner	Organization owner	Full access to everything
admin	Administrator	Manage users, full API access
developer	API Developer	Full API access, no user management
viewer	Read-only access	View only, no write operations
billing	Billing manager	Billing and subscription management

---

Integration Example

from alaikis import AlaikisClient

client = AlaikisClient(api_key="YOUR_API_TOKEN")

# Get current user info
current_user = client.users.get_me()
print(f"Logged in as: {current_user.data.name}")
print(f"Organization: {current_user.data.organization.name}")
print(f"API Usage: {current_user.data.api_usage.this_month} / {current_user.data.api_usage.limit}")

# List team members
team_members = client.users.list(role="developer")
print(f"\nTeam Members ({team_members.data.total} total):")
for user in team_members.data.users:
    print(f"  - {user.name} ({user.email}) - Last login: {user.last_login}")

# Get user activity
activity = client.users.get_activity(current_user.data.user_id)
print(f"\nRecent Activity:")
for act in activity.data.activities[:5]:
    print(f"  [{act.timestamp}] {act.action} - {act.endpoint} ({act.response_time_ms}ms)")

---

Error Codes

Code	HTTP Status	Description
USER_NOT_FOUND	404	User does not exist
INSUFFICIENT_PERMISSIONS	403	Not authorized for this action
EMAIL_ALREADY_EXISTS	409	Email already registered
INVALID_ROLE	400	Invalid role specified
LAST_OWNER_CANNOT_BE_DELETED	400	Cannot delete the last organization owner