logoSemaphor

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:

https://semaphor.cloud/api/management/v1/tenant-users

All endpoints require authentication and organization-level permissions.

Example: Create a Tenant User via API

1. Get a project token

curl -X POST https://semaphor.cloud/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "type": "project",
    "projectId": "your-project-id",
    "projectSecret": "your-project-secret",
    "orgUserId": "your-org-user-id"
  }'

2. Create a tenant user

curl -X POST https://semaphor.cloud/api/management/v1/tenant-users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "custom-tenant-user-id", // optional, if not provided, a random id will be generated
    "email": "john.doe@example.com",
    "name": "John Doe",
    "tenantId": "t_12345678-1234-1234-1234-123456789abc",
    "role": "POWER_USER",
    "department": "Sales"
  }'

Expected Response:

{
  "id": "tu_12345678-1234-1234-1234-123456789abc",
  "email": "john.doe@example.com",
  "name": "John Doe",
  "role": "POWER_USER",
  "department": "Sales",
  "isActive": true,
  "tenantId": "t_12345678-1234-1234-1234-123456789abc",
  "tenantName": "Acme Corp",
  "organizationName": "Acme Organization",
  "type": "tenant",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

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 email
  • active (optional): Filter by active status (true/false)
  • tenantId (optional): Filter by specific tenant
  • limit (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:

curl -X GET "https://semaphor.cloud/api/management/v1/tenant-users?search=john&active=true&limit=20" \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "users": [
    {
      "id": "tu_12345678-1234-1234-1234-123456789abc",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "role": "POWER_USER",
      "department": "Sales",
      "isActive": true,
      "tenantId": "t_12345678-1234-1234-1234-123456789abc",
      "tenantName": "Acme Corp",
      "organizationName": "Acme Organization",
      "type": "tenant",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 1,
  "userContext": {
    "type": "organization",
    "userId": "u_12345678-1234-1234-1234-123456789abc",
    "tenantId": null,
    "organizationId": "o_12345678-1234-1234-1234-123456789abc",
    "role": "ADMIN",
    "isSuperAdmin": false,
    "permissions": {
      "canShareWithTenants": true,
      "canShareWithOrgUsers": true,
      "canShareWithOtherTenants": false
    }
  }
}

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:

{
  "email": "user@example.com",
  "name": "User Name",
  "tenantId": "t_12345678-1234-1234-1234-123456789abc",
  "role": "VIEWER",
  "department": "Marketing"
}

Required Fields:

  • email: Valid email address
  • name: User's full name
  • tenantId: ID of the tenant to assign the user to

Optional Fields:

  • role: User role (VIEWER or POWER_USER, default: VIEWER)
  • department: User's department

Example Request:

curl -X POST https://semaphor.cloud/api/management/v1/tenant-users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.smith@example.com",
    "name": "Jane Smith",
    "tenantId": "t_12345678-1234-1234-1234-123456789abc",
    "role": "POWER_USER",
    "department": "Engineering"
  }'

Example Response:

{
  "id": "tu_87654321-4321-4321-4321-cba987654321",
  "email": "jane.smith@example.com",
  "name": "Jane Smith",
  "role": "POWER_USER",
  "department": "Engineering",
  "isActive": true,
  "tenantId": "t_12345678-1234-1234-1234-123456789abc",
  "tenantName": "Acme Corp",
  "organizationName": "Acme Organization",
  "type": "tenant",
  "createdAt": "2024-01-15T11:00:00.000Z"
}

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:

{
  "name": "Updated Name",
  "email": "updated@example.com",
  "role": "POWER_USER",
  "isActive": true,
  "department": "Updated Department"
}

All fields are optional. Only provided fields will be updated.

Example Request:

curl -X PUT https://semaphor.cloud/api/management/v1/tenant-users/tu_12345678-1234-1234-1234-123456789abc \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "POWER_USER",
    "department": "Senior Sales"
  }'

Example Response:

{
  "message": "Tenant user updated successfully",
  "user": {
    "id": "tu_12345678-1234-1234-1234-123456789abc",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "role": "POWER_USER",
    "department": "Senior Sales",
    "isActive": true,
    "tenantId": "t_12345678-1234-1234-1234-123456789abc",
    "tenantName": "Acme Corp",
    "organizationName": "Acme Organization",
    "type": "tenant",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T12:00:00.000Z"
  }
}

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:

curl -X DELETE https://semaphor.cloud/api/management/v1/tenant-users/tu_12345678-1234-1234-1234-123456789abc \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "message": "Tenant user deleted successfully",
  "deletedUser": {
    "id": "tu_12345678-1234-1234-1234-123456789abc",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "tenantName": "Acme Corp"
  }
}

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:

{
  "error": "Email, name, and tenantId are required"
}

401 Unauthorized:

{
  "error": "Invalid or missing authentication token"
}

403 Forbidden:

{
  "error": "Only organization users can create tenant users"
}

404 Not Found:

{
  "error": "Tenant user not found or access denied"
}

409 Conflict:

{
  "error": "User with this email already exists in this tenant"
}

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

Previous

Tenants API

Next

Tokens API

On this page