Tenant Users API
Create and Manage tenant users via the Semaphor Management API
Overview
The Tenant Users API allows you to create, retrieve, update, and delete tenant users programmatically. This API is designed for organization administrators to manage users within their tenants.
Base path:
All endpoints require authentication and organization-level permissions.
Example: Create a Tenant User via API
1. Get a project token
2. Create a tenant user
Expected Response:
List Tenant Users
GET /tenant-users
- Returns a list of tenant users with pagination and filtering options.
- Only organization users with ADMIN or SUPER_ADMIN roles can access this endpoint.
Query Parameters:
search
(optional): Search by name or emailactive
(optional): Filter by active status (true
/false
)tenantId
(optional): Filter by specific tenantlimit
(optional): Number of results per page (default: 50)offset
(optional): Number of results to skip (default: 0)page
(optional): Page number (alternative to offset)pageSize
(optional): Results per page (alternative to limit)
Example Request:
Example Response:
Create Tenant User
POST /tenant-users
- Creates a new tenant user.
- Only organization users with ADMIN or SUPER_ADMIN roles can create tenant users.
Request Body:
Required Fields:
email
: Valid email addressname
: User's full nametenantId
: ID of the tenant to assign the user to
Optional Fields:
role
: User role (VIEWER
orPOWER_USER
, default:VIEWER
)department
: User's department
Example Request:
Example Response:
Update Tenant User
PUT /tenant-users/:id
- Updates an existing tenant user's information.
- Only organization users with ADMIN or SUPER_ADMIN roles can update tenant users.
Request Body:
All fields are optional. Only provided fields will be updated.
Example Request:
Example Response:
Delete Tenant User
DELETE /tenant-users/:id
- Deletes a tenant user.
- Only organization users with ADMIN or SUPER_ADMIN roles can delete tenant users.
- Cannot delete the default owner of a tenant.
Example Request:
Example Response:
User Roles
The API supports the following user roles:
- VIEWER: Basic access to view dashboards and reports
- POWER_USER: Enhanced access with ability to create and modify content
Error Handling
Common error responses:
400 Bad Request:
401 Unauthorized:
403 Forbidden:
404 Not Found:
409 Conflict:
Notes
- All endpoints require authentication (Bearer token)
- Only organization users with ADMIN or SUPER_ADMIN roles can manage tenant users
- Email addresses must be unique within each tenant
- Users cannot be deleted if they are the default owner of a tenant
- The API automatically validates email format and required fields
- All timestamps are returned in ISO 8601 format