Tenants API

Overview

The Tenants API allows you to create, retrieve, update, and delete tenants programmatically. This API is designed for organization administrators to manage tenant organizations within their system.

Base path:

https://semaphor.cloud/api/management/v1/tenants

All endpoints require authentication and organization-level permissions.

Example: Create a Tenant 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

curl -X POST https://semaphor.cloud/api/management/v1/tenants \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation"
  }'

Expected Response:

{
  "id": "t_12345678-1234-1234-1234-123456789abc",
  "name": "Acme Corporation",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

List Tenants

GET /tenants

Returns a list of tenants with pagination and filtering options.
Only organization users can access this endpoint.

Query Parameters:

search (optional): Search by tenant name
limit (optional): Number of results per page (default: 500)
offset (optional): Number of results to skip (default: 0)

Example Request:

curl -X GET "https://semaphor.cloud/api/management/v1/tenants?search=acme&limit=20" \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "tenants": [
    {
      "id": "t_12345678-1234-1234-1234-123456789abc",
      "name": "Acme Corporation",
      "organizationId": "o_12345678-1234-1234-1234-123456789abc",
      "organization": {
        "id": "o_12345678-1234-1234-1234-123456789abc",
        "name": "Acme Organization"
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "defaultOwnerId": "tu_12345678-1234-1234-1234-123456789abc",
      "defaultOwner": {
        "name": "John Doe",
        "email": "john.doe@acme.com"
      },
      "userCount": 5
    }
  ],
  "total": 1
}

Create Tenant

POST /tenants

Creates a new tenant within the organization.
Only organization users can create tenants.

Request Body:

{
  "name": "New Tenant Name"
}

Required Fields:

name: Tenant name (must be unique within the organization)

Optional Fields:

defaultOwnerId: ID of the tenant user who will be the default owner

Example Request:

curl -X POST https://semaphor.cloud/api/management/v1/tenants \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Beta Corporation"
  }'

Example Response:

{
  "id": "t_87654321-4321-4321-4321-cba987654321",
  "name": "Beta Corporation",
  "createdAt": "2024-01-15T11:00:00.000Z",
  "updatedAt": "2024-01-15T11:00:00.000Z",
  "defaultOwnerId": "tu_87654321-4321-4321-4321-cba987654321",
  "defaultOwner": {
    "name": "Jane Smith",
    "email": "jane.smith@beta.com"
  }
}

Get Tenant by ID

GET /tenants/:id

Returns details for a specific tenant, including user count and default owner information.
Only organization users can access this endpoint.

Example Request:

curl -X GET https://semaphor.cloud/api/management/v1/tenants/t_12345678-1234-1234-1234-123456789abc \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "id": "t_12345678-1234-1234-1234-123456789abc",
  "name": "Acme Corporation",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "defaultOwnerId": "tu_12345678-1234-1234-1234-123456789abc",
  "defaultOwner": {
    "name": "John Doe",
    "email": "john.doe@acme.com"
  },
  "userCount": 5
}

Update Tenant

PUT /tenants/:id

Updates an existing tenant's information.
Only organization users can update tenants.

Request Body:

{
  "name": "Updated Tenant Name",
  "defaultOwnerId": "tu_87654321-4321-4321-4321-cba987654321"
}

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

Example Request:

curl -X PUT https://semaphor.cloud/api/management/v1/tenants/t_12345678-1234-1234-1234-123456789abc \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation (Updated)",
    "defaultOwnerId": "tu_87654321-4321-4321-4321-cba987654321"
  }'

Example Response:

{
  "id": "t_12345678-1234-1234-1234-123456789abc",
  "name": "Acme Corporation (Updated)",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T12:00:00.000Z",
  "defaultOwnerId": "tu_87654321-4321-4321-4321-cba987654321",
  "defaultOwner": {
    "name": "Jane Smith",
    "email": "jane.smith@acme.com"
  }
}

Delete Tenant

DELETE /tenants/:id

Deletes a tenant.
Only organization users can delete tenants.
Cannot delete a tenant that has active users.

Example Request:

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

Example Response:

{
  "message": "Tenant deleted successfully"
}

Tenant Management

Default Owner

Each tenant has a default owner who is responsible for the tenant:

The default owner is a tenant user who has special privileges
Default owners cannot be deleted from the tenant
You can change the default owner by updating the tenant

User Count

The API provides user count information for each tenant:

Shows the total number of active tenant users
Helps with tenant management and capacity planning
Updated automatically when users are added or removed

Error Handling

Common error responses:

400 Bad Request:

{
  "error": "Name is required"
}

401 Unauthorized:

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

403 Forbidden:

{
  "error": "Permission denied"
}

404 Not Found:

{
  "error": "Tenant not found"
}

409 Conflict:

{
  "error": "Tenant with this name already exists in the organization"
}

409 Conflict (Delete with Users):

{
  "error": "Cannot delete tenant with active users. Please remove all users first."
}

Notes

All endpoints require authentication (Bearer token)
Only organization users can manage tenants
Tenant names must be unique within each organization
Tenants cannot be deleted if they have active users
The API automatically validates required fields
All timestamps are returned in ISO 8601 format
Default owners have special privileges and cannot be deleted
User counts are automatically maintained and updated

Tenants API

On this page