Skip to main content

​
Users API

The Users API handles user registration, authentication, and profile management. All user data is stored in MongoDB with secure password hashing.

​
User Model

The User model represents a user in the system:
​
id
string
Unique user identifier (UUID v4)
​
email
string
User’s email address (unique, used for login)
​
name
string
User’s full name
​
organization
string
Organization name (defaults to “Default Organization”)
​
role
string
User role: "user" or "admin" (defaults to “user”)
​
mfa_enabled
boolean
Whether multi-factor authentication is enabled (defaults to true)
​
created_at
datetime
Timestamp when the user was created (ISO 8601 format)

​
Extended Fields (SSO)

For users who authenticate via SSO:
​
sso_provider
string
SSO provider name (e.g., “zitadel”)
​
sso_sub
string
SSO subject identifier from OIDC
​
roles
array
Array of role strings from SSO provider
​
groups
array
Array of group strings from SSO provider
​
picture
string
Profile picture URL from SSO provider
​
last_login
datetime
Timestamp of last login (ISO 8601 format)

​
Register User

Create a new user account with email and password. 
curl -X POST https://your-domain.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecureP@ssw0rd!",
    "name": "John Doe",
    "organization": "Acme Corporation"
  }'

​
Request Body

​
email
string
required
User’s email address (must be unique)
​
password
string
required
User’s password (hashed with SHA-256 before storage)
​
name
string
required
User’s full name
​
organization
string
Organization name (optional, defaults to “Default Organization”)

​
Response

​
access_token
string
Authentication token for API requests
​
token_type
string
Always “bearer”
​
user
object
Created user object
Response Example
{
  "access_token": "xK9mP2nQ4rS6tU8vW0xY2zA4bC6dE8fG0hI2jK4lM6nO8pQ0rS2tU4vW6xY8zA0b",
  "token_type": "bearer",
  "user": {
    "id": "a3d2c1b0-9876-4321-abcd-ef1234567890",
    "email": "[email protected]",
    "name": "John Doe",
    "organization": "Acme Corporation",
    "role": "user",
    "mfa_enabled": true
  }
}

​
Automatic Actions

When a user registers:
  1. Email uniqueness is validated
  2. Password is hashed using SHA-256
  3. User record is created in MongoDB
  4. Access token is generated
  5. Audit log entry is created: "register" action

​
Error Responses

​
400
error
{
  "detail": "Email already registered"
}

​
Login User

Authenticate an existing user with email and password. 
curl -X POST https://your-domain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecureP@ssw0rd!"
  }'

​
Request Body

​
email
string
required
User’s email address
​
password
string
required
User’s password

​
Response

Same structure as registration - returns AuthToken with user profile.

​
Automatic Actions

When a user logs in:
  1. Email is looked up in database
  2. Password hash is verified
  3. Access token is generated
  4. Audit log entry is created: "login" action

​
Error Responses

​
401
error
{
  "detail": "Invalid credentials"
}
Returned when email doesn’t exist or password is incorrect

​
Get Current User

Retrieve the authenticated user’s profile. 
curl https://your-domain.com/api/auth/me \
  -H "Authorization: Bearer your-token-here"

​
Response

{
  "id": "a3d2c1b0-9876-4321-abcd-ef1234567890",
  "email": "[email protected]",
  "name": "John Doe",
  "organization": "Acme Corporation",
  "role": "user",
  "mfa_enabled": true
}

​
Error Responses

​
401
error
{
  "detail": "Not authenticated"
}
Missing or invalid Authorization header
​
401
error
{
  "detail": "Invalid token"
}
Token not found in active tokens

​
Logout

Invalidate the current authentication token. 
curl -X POST https://your-domain.com/api/auth/logout \
  -H "Authorization: Bearer your-token-here"

​
Response

{
  "message": "Logged out successfully"
}

​
Automatic Actions

When a user logs out:
  1. Token is removed from active tokens
  2. Audit log entry is created: "logout" action

​
Password Security

Passwords are hashed using SHA-256. For production use, consider upgrading to bcrypt or argon2 for enhanced security.
Password hashing implementation: 
import hashlib

def hash_password(password: str) -> str:
    return hashlib.sha256(password.encode()).hexdigest()

​
User Roles

​
User Role

Standard users can:
  • Access their own workspaces
  • Launch and stop sessions
  • View their own audit logs
  • View their profile

​
Admin Role

Admins can:
  • All user permissions
  • Create, update, and delete workspaces
  • View all audit logs
  • Manage policies
  • View all users and organizations

​
Integration with Other APIs

The user context is used across all authenticated endpoints:
  • Workspaces: User ID tracks who launches workspaces
  • Sessions: User email and ID are stored in session records
  • Audit Logs: All actions are attributed to the authenticated user
  • Organizations: Users belong to organizations

​
Example: Complete Registration Flow

import requests

BASE_URL = "https://your-domain.com/api"

# 1. Register a new user
register_response = requests.post(
    f"{BASE_URL}/auth/register",
    json={
        "email": "[email protected]",
        "password": "MySecurePassword123!",
        "name": "Jane Smith",
        "organization": "Tech Startup Inc"
    }
)

auth_data = register_response.json()
token = auth_data["access_token"]
user = auth_data["user"]

print(f"User {user['name']} registered successfully!")
print(f"Role: {user['role']}")
print(f"MFA Enabled: {user['mfa_enabled']}")

# 2. Use the token to access protected endpoints
headers = {"Authorization": f"Bearer {token}"}

# Get current user profile
profile = requests.get(f"{BASE_URL}/auth/me", headers=headers).json()
print(f"Profile: {profile}")

# List available workspaces
workspaces = requests.get(f"{BASE_URL}/workspaces", headers=headers).json()
print(f"Available workspaces: {len(workspaces)}")

# 3. Logout when done
requests.post(f"{BASE_URL}/auth/logout", headers=headers)
print("Logged out successfully")

Build docs developers (and LLMs) love

Get started for freeTalk to us