logoSemaphor

Tenants API

Create and Manage tenants via the Semaphor Management 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 '{
    "id": "custom-tenant-id", // optional, if not provided, a random id will be generated
    "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

Previous

Visuals API

Next

Tenant Users API

On this page