Users API

The Users API provides endpoints for user management operations. User authentication is handled through Zitadel, with BotServer maintaining session associations and user preferences.

Overview

User management in General Bots follows a federated model:

Zitadel: Primary identity provider (authentication, SSO, user creation)
BotServer: Session management, preferences, bot-specific user data

Endpoints

Get Current User

GET /api/users/me

Returns current authenticated user information.

Headers:

Authorization: Bearer {session_token}

Response:

{
  "user_id": "user-123",
  "username": "john_doe",
  "email": "john@example.com",
  "display_name": "John Doe",
  "avatar_url": "/api/users/user-123/avatar",
  "roles": ["user", "manager"],
  "created_at": "2024-01-01T00:00:00Z",
  "last_login": "2024-01-15T10:30:00Z"
}

Get User by ID

GET /api/users/:id

Retrieve specific user details.

Required Permission: admin:users or same user

Response:

{
  "user_id": "user-123",
  "username": "john_doe",
  "email": "john@example.com",
  "display_name": "John Doe",
  "status": "active",
  "created_at": "2024-01-01T00:00:00Z"
}

List Users

GET /api/users

List users in the organization.

Required Permission: admin:users

Query Parameters:

limit - Number of results (default: 50, max: 100)
offset - Pagination offset
status - Filter by status (active/suspended/inactive)
role - Filter by role
search - Search by name or email

Response:

{
  "users": [
    {
      "user_id": "user-123",
      "username": "john_doe",
      "email": "john@example.com",
      "display_name": "John Doe",
      "status": "active",
      "roles": ["user", "manager"]
    },
    {
      "user_id": "user-456",
      "username": "jane_smith",
      "email": "jane@example.com",
      "display_name": "Jane Smith",
      "status": "active",
      "roles": ["user"]
    }
  ],
  "total": 47,
  "limit": 50,
  "offset": 0
}

Update User

PUT /api/users/:id

Update user information.

Required Permission: admin:users or same user (limited fields)

Request:

{
  "display_name": "John D. Doe",
  "avatar_url": "https://example.com/avatar.jpg"
}

Admin-only fields:

{
  "status": "suspended",
  "roles": ["user"]
}

Response:

{
  "user_id": "user-123",
  "status": "updated",
  "updated_fields": ["display_name"]
}

Update User Settings

PUT /api/users/:id/settings

Update user preferences.

Request:

{
  "theme": "dark",
  "language": "en",
  "notifications": {
    "email": true,
    "push": false,
    "digest": "daily"
  },
  "default_bot": "support-bot"
}

Response:

{
  "status": "updated",
  "settings": {
    "theme": "dark",
    "language": "en"
  }
}

Get User Settings

GET /api/users/:id/settings

Retrieve user preferences.

Response:

{
  "theme": "dark",
  "language": "en",
  "timezone": "America/New_York",
  "notifications": {
    "email": true,
    "push": false,
    "digest": "daily"
  },
  "default_bot": "support-bot"
}

Suspend User

POST /api/users/:id/suspend

Suspend a user account.

Required Permission: admin:users

Request:

{
  "reason": "Policy violation"
}

Response:

{
  "user_id": "user-123",
  "status": "suspended",
  "suspended_at": "2024-01-15T10:30:00Z"
}

Activate User

POST /api/users/:id/activate

Reactivate a suspended user.

Required Permission: admin:users

Response:

{
  "user_id": "user-123",
  "status": "active",
  "activated_at": "2024-01-15T10:30:00Z"
}

Delete User

DELETE /api/users/:id

Deactivate/delete user account.

Required Permission: admin:users

Response:

{
  "user_id": "user-123",
  "status": "deleted",
  "deleted_at": "2024-01-15T10:30:00Z"
}

User Sessions

List User Sessions

GET /api/users/:id/sessions

List active sessions for a user.

Response:

{
  "sessions": [
    {
      "session_id": "sess-001",
      "bot_id": "support-bot",
      "started_at": "2024-01-15T09:00:00Z",
      "last_activity": "2024-01-15T10:30:00Z",
      "device": "Chrome on Windows"
    }
  ]
}

Terminate Session

DELETE /api/users/:id/sessions/:session_id

End a specific user session.

Response:

{
  "session_id": "sess-001",
  "status": "terminated"
}

Terminate All Sessions

DELETE /api/users/:id/sessions

End all user sessions (logout everywhere).

Response:

{
  "terminated_count": 3,
  "status": "all_sessions_terminated"
}

User Authentication Flow

POST /api/users/login

Authenticate user (redirects to Zitadel).

Request:

{
  "email": "user@example.com",
  "password": "password",
  "remember_me": true
}

Response:

{
  "redirect_url": "https://auth.yourdomain.com/oauth/authorize?..."
}

Logout

POST /api/users/logout

End current session.

Response:

{
  "status": "logged_out",
  "redirect_url": "/"
}

Register

POST /api/users/register

Request:

{
  "email": "newuser@example.com",
  "username": "newuser",
  "password": "SecurePassword123!",
  "display_name": "New User"
}

Response:

{
  "user_id": "user-789",
  "status": "pending_verification",
  "message": "Check your email to verify your account"
}

User Management via Zitadel

For full user management, access Zitadel admin console:

Access Console: http://localhost:8080 (or your Zitadel URL)
Create Users: Organization → Users → Add
Manage Roles: Users → Select User → Authorizations
Reset Passwords: Users → Select User → Actions → Reset Password
Configure SSO: Settings → Identity Providers

Database Schema

BotServer maintains minimal user data:

-- users table (synced from Zitadel)
CREATE TABLE users (
    id UUID PRIMARY KEY,
    zitadel_id TEXT UNIQUE,
    username TEXT,
    email TEXT,
    display_name TEXT,
    avatar_url TEXT,
    status TEXT DEFAULT 'active',
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- user_settings table
CREATE TABLE user_settings (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    setting_key TEXT NOT NULL,
    setting_value TEXT,
    UNIQUE(user_id, setting_key)
);

-- user_sessions table
CREATE TABLE sessions (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    bot_id UUID,
    status TEXT DEFAULT 'active',
    device_info TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    last_activity TIMESTAMPTZ DEFAULT NOW()
);

Error Handling

Status Code	Error	Description
400	`invalid_request`	Malformed request
401	`unauthorized`	Not authenticated
403	`forbidden`	Insufficient permissions
404	`user_not_found`	User doesn’t exist
409	`conflict`	Username/email already exists
422	`validation_error`	Invalid field values

Rate Limits

Endpoint	Limit
Login	10/minute per IP
Register	5/hour per IP
User List	60/minute per user
User Update	30/minute per user

BASIC Integration

Access user information in scripts:

' Get current user info
user_name = GET user_name
user_email = GET user_email

' Greet by name
TALK "Hello, " + user_name + "!"

' Check user role
role = GET role
IF role = "admin" THEN
    TALK "Welcome, administrator!"
END IF

General Bots Documentation

Users API

Overview

Endpoints

Get Current User

Get User by ID

List Users

Update User

Update User Settings

Get User Settings

Suspend User

Activate User

Delete User

User Sessions

List User Sessions

Terminate Session

Terminate All Sessions

User Authentication Flow

Logout

Register

User Management via Zitadel

Database Schema

Error Handling

Rate Limits

BASIC Integration

See Also

Keyboard shortcuts

General Bots Documentation