Create user
Create a new user with flexible organization assignment.
This endpoint creates a user account in the platform database and authentication system. Unlike the organization-scoped endpoint, this allows creating users with organization_id specified in the request body. Use this for bulk user creation or when organization context is not available in URL.
Context: - Creates user in platform database and authentication system - Sends email invitation to user with password setup link - Requires organization_id in request body (no path parameter) - User starts in inactive status until they accept invitation - Email must be unique within the organization - User role determines permission level - Authentication synchronization ensures consistency
Behavior: 1. Validates organization_id is provided in request body 2. Validates organization exists and is active 3. Checks email is not already used in this organization 4. Creates user record in platform database 5. Creates user in authentication system 6. Sends email invitation to user with password setup link 7. Returns user details (user must accept invitation separately) Side Effects: - User created in platform database - User created in authentication system (pending invitation acceptance) - Email invitation sent to user's email address - User appears in organization user lists immediately - User cannot log in until they accept invitation and set password
Use Cases: - Bulk user creation via CSV import or API integration - Create users when organization context not available in URL - Automated user provisioning from external systems - Onboard multiple users across different organizations - Integration with identity providers (SCIM, SAML)
Comparison with Organization-Scoped Endpoint: - POST /admin/organizations/{id}/users - Use when organization known in URL - POST /admin/users - Use for bulk operations or flexible creation
Related Endpoints: - POST /admin/organizations/{id}/users - Alternative with organization in URL - GET /admin/users/{user_id} - View created user details - GET /admin/users - List all users - DELETE /admin/users/{user_id} - Remove user if created by mistake
Header Parameters
Body Parameters
User's email address. Required, must be valid email format. Used for login, authentication, and invitation emails. Must be unique within the organization. Email invitation automatically sent to this address upon user creation.
User's first name. Required. Used in UI displays and email communications. Constraints: 1-100 characters, cannot be empty.
Whether user account is active. Optional, defaults to True. Inactive users cannot log in or access the system. Note: User must still accept email invitation to log in, even if is_active is True. Default: True (user created in active state pending invitation acceptance)
User's last name. Required. Used in UI displays and email communications. Constraints: 1-100 characters, cannot be empty.
User's role within the organization. Required. Determines permission level and feature access. Valid values: 'org_admin', 'backoffice', 'app_user', 'integration'.
Role permissions:
- 'org_admin': Full access to organization resources and user management
- 'backoffice': Super admin with platform-level access
- 'app_user': Can create and manage own flows and executions
- 'integration': Service account for integrations and automated workflows
Response
Response Attributes
Timestamp when user was created. Format: ISO 8601 UTC (e.g., '2025-01-23T15:30:00Z').
User's email address. Must be unique within organization. Used for login, authentication, and notifications. Synchronized with authentication system. Can be updated after user creation.
User's first name. Used in UI displays, emails, and user identification. Can be updated after user creation.
Unique identifier for the user. Format: UUID v4. Synchronized with authentication system user ID.
User's last name. Used in UI displays, emails, and user identification. Can be updated after user creation.
Identifier of the user or system that last modified this user. Can be user UUID or system identifier (e.g., 'system', 'admin'). Used for audit trail and change attribution.
UUID of the organization this user belongs to. Users are scoped to a single organization (no cross-org access). Organization must exist and determines user's data access scope.
User's role within the organization. Determines permission level. Valid values: 'org_admin', 'backoffice', 'app_user', 'integration'.
Role permissions:
- 'org_admin': Full organization access and user management
- 'backoffice': Super admin with platform-level access
- 'app_user': Regular user who can create and manage own flows and executions
- 'integration': Service account for integrations and automated workflows
User's current account status. Valid values: 'active', 'inactive'.
'active': User can log in and access the system. 'inactive': User cannot log in; account is disabled. Note: Even active users must accept email invitation to log in initially.
Timestamp when user was last modified. Updated automatically on any field change. Format: ISO 8601 UTC (e.g., '2025-01-24T10:45:00Z'). Used for change tracking and audit logs.
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.
Show child attributes
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.
Show child attributes
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.
Show child attributes
Response Attributes
Show child attributes
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.