Skip to main content

​
Overview

Tenants are the top-level administrative units in Pulsar. Each tenant can have multiple namespaces and represents an organization or team. The Tenants API allows you to create, configure, and manage tenants. Base Path: /admin/v2/tenants

​
List Tenants

Get the list of all existing tenants in the cluster. 
GET /admin/v2/tenants

​
Response

​
tenants
array
List of tenant names

​
Example

curl -X GET http://localhost:8080/admin/v2/tenants \
  -H "Authorization: Bearer <token>"

​
Response Example

[
  "public",
  "sample",
  "my-tenant"
]

​
Get Tenant Info

Retrieve the configuration for a specific tenant. 
GET /admin/v2/tenants/{tenant}

​
Path Parameters

​
tenant
string
required
The tenant name

​
Response

​
adminRoles
array
List of admin roles for this tenant
​
allowedClusters
array
List of clusters this tenant is allowed to use

​
Example

curl -X GET http://localhost:8080/admin/v2/tenants/my-tenant \
  -H "Authorization: Bearer <token>"

​
Response Example

{
  "adminRoles": ["admin", "ops-team"],
  "allowedClusters": ["us-west", "us-east"]
}

​
Create Tenant

Create a new tenant with the specified configuration. 
PUT /admin/v2/tenants/{tenant}

​
Path Parameters

​
tenant
string
required
The tenant name to create. Must be a valid identifier without ’/’ characters.

​
Request Body

​
adminRoles
array
List of roles that have admin access to this tenant
​
allowedClusters
array
required
List of clusters this tenant can use. Cannot be empty.

​
Example

curl -X PUT http://localhost:8080/admin/v2/tenants/my-tenant \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "adminRoles": ["admin", "ops-team"],
    "allowedClusters": ["us-west", "us-east"]
  }'

​
Response Codes

CodeDescription
204Tenant created successfully
403Don’t have admin permissions
409Tenant already exists
412Invalid tenant name or clusters don’t exist

​
Update Tenant

Update the configuration of an existing tenant. 
POST /admin/v2/tenants/{tenant}

​
Path Parameters

​
tenant
string
required
The tenant name to update

​
Request Body

​
adminRoles
array
Updated list of admin roles
​
allowedClusters
array
required
Updated list of allowed clusters

​
Example

curl -X POST http://localhost:8080/admin/v2/tenants/my-tenant \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "adminRoles": ["admin", "ops-team", "new-admin"],
    "allowedClusters": ["us-west", "us-east", "eu-central"]
  }'

​
Response Codes

CodeDescription
204Tenant updated successfully
403Don’t have admin permissions
404Tenant doesn’t exist
412Invalid configuration or clusters don’t exist

​
Delete Tenant

Delete a tenant and all its namespaces and topics. 
DELETE /admin/v2/tenants/{tenant}

​
Path Parameters

​
tenant
string
required
The tenant name to delete

​
Query Parameters

​
force
boolean
default:"false"
Force delete even if namespaces exist

​
Example

curl -X DELETE http://localhost:8080/admin/v2/tenants/my-tenant \
  -H "Authorization: Bearer <token>"

​
Response Codes

CodeDescription
204Tenant deleted successfully
403Don’t have admin permissions
404Tenant doesn’t exist
409Tenant has active namespaces (use force=true)

​
Error Handling

​
Common Errors

You don’t have super-user or tenant admin privileges.Solution: Ensure you’re authenticated with proper credentials.
A tenant with this name already exists.Solution: Choose a different name or update the existing tenant.
The tenant name contains invalid characters.Solution: Use only alphanumeric characters, hyphens, and underscores.
One or more specified clusters don’t exist.Solution: Verify cluster names and create missing clusters first.

​
Best Practices

​
Naming Conventions

  • Use lowercase names for consistency
  • Avoid special characters except hyphens and underscores
  • Use descriptive names that reflect the organization or team

​
Cluster Assignment

  • Assign tenants to appropriate clusters based on geographic location
  • Consider data residency and compliance requirements
  • Plan for multi-region deployments

​
Role Management

  • Use the principle of least privilege
  • Create specific roles for different administrative levels
  • Regularly review and update admin roles

​
Tenant Lifecycle

  1. Create: Define tenant with appropriate clusters
  2. Configure: Set up namespaces and policies
  3. Monitor: Track usage and performance
  4. Update: Adjust configuration as needs change
  5. Delete: Clean up when no longer needed

Namespaces API

Manage namespaces within tenants

Clusters API

Configure cluster settings

Build docs developers (and LLMs) love

Get started for freeTalk to us