5. Tenants

Creating, listing, and configuring the tenants that partition a realm, including each tenant’s StorageSet quota allocations.

Endpoint Summary

GET /api/v1/tenants

List tenants

Returns a list of all tenants, each carrying the network status the realm manager reports for it. Any platform role that grants tenants:list may call it.

Authentication: required (PasswordLogin or BearerJWT).

Responses

Response Body (200, ListTenantResponse)

Example

{
   "tenants" : [
      {
         "created_at" : "2026-03-02T12:00:00Z",
         "description" : "FinTech tenant",
         "id" : "e97b94d6-9cc1-4325-a267-1064ae538ccd",
         "name" : "fintech",
         "status" : "active",
         "updated_at" : "2026-03-02T12:00:00Z"
      }
   ],
   "total" : 1
}

POST /api/v1/tenants

Create tenant

Creates a new tenant with the specified configuration and returns its ID. Platform Admin only.

Authentication: required (PasswordLogin or BearerJWT).

Request Body (application/json, required)

Schema: TenantCreateRequest

Request payload for creating a tenant.

Responses

Response Body (201, TenantCreateResponse)

Example

{
   "id" : "e97b94d6-9cc1-4325-a267-1064ae538ccd"
}

GET /api/v1/tenants/archived

List archived tenants

Returns the deleted tenants kept in the platform archive, newest deletion first. Platform Admin only. An archived tenant exists in neither the storage fabric nor the configuration store: the entry is all that is left of it, and it is never removed. Its display name and contact email have no other surviving copy.

Authentication: required (PasswordLogin or BearerJWT).

Responses

Response Body (200, ListArchivedTenantResponse)

Example

{
   "tenants" : [
      {
         "created_at" : "2026-01-10T08:00:00Z",
         "deleted_at" : "2026-04-02T11:20:00Z",
         "description" : "Decommissioned engineering tenant",
         "display_name" : "Engineering (retired)",
         "email" : "eng-owner@vdura.example.com",
         "id" : "3f2b1c0d-5e4a-4b8c-9d7e-6a5b4c3d2e1f",
         "name" : "oldeng",
         "status" : "archived",
         "updated_at" : "2026-04-02T11:15:00Z"
      }
   ],
   "total" : 1
}

GET /api/v1/tenants/roles

List roles available on the current tenant

Returns the roles available on the caller’s current tenant - resolved from the auth context, with no tenant_id path parameter. The response is a roles array with a total; each entry carries the role id and the permissions map of resource to the actions that role may perform on it. Roles are read from the current tenant’s RBAC policy, so Platform and Tenant contexts each return the role set defined and enforced on their own tenant.

Authentication: required (PasswordLogin or BearerJWT).

Responses

Response Body (200, TenantRolesResponse)

Example

{
   "roles" : [
      {
         "id" : "admin",
         "permissions" : {
            "roles" : [
               "view",
               "update"
            ],
            "tenants" : [
               "view"
            ],
            "users" : [
               "list",
               "view",
               "create",
               "update",
               "delete"
            ],
            "volumes" : [
               "list",
               "view",
               "create",
               "update",
               "delete",
               "action"
            ]
         },
         "reserved" : false
      },
      {
         "id" : "s3-gateway",
         "permissions" : {
            "fs-users" : [
               "read-s3-secret",
               "list"
            ]
         },
         "reserved" : true
      }
   ],
   "total" : 2
}

GET /api/v1/tenants/{tenant_id}

Get tenant info

Returns details for a specific tenant by its ID, including the network status the realm manager reports for it. The platform tenant may view any tenant, and a Tenant Admin may view only their own tenant.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, GetTenantResponse)

PATCH /api/v1/tenants/{tenant_id}

Update tenant

Updates a tenant using PATCH semantics. Only the fields provided in the request are modified. Platform Admin only.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Request Body (application/json, required)

Schema: TenantPatchRequest

Request payload for updating a tenant via PATCH.

Allows partial updates. At least one field must be provided. Patchable fields: display_name, email, description, auth_settings. Tenant Admin can update display_name, email, description and auth_settings. name is the immutable handle and is not patchable.

Responses

DELETE /api/v1/tenants/{tenant_id}

Delete tenant

Deletes the specified tenant by its ID, removing its records from both the storage fabric and the configuration store and leaving an entry in the platform archive. Platform Admin only. Safe to repeat: a delete interrupted part-way is resumed by sending it again.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

GET /api/v1/tenants/{tenant_id}/storagesets

List tenant storageset quota allocations

Lists the storageset quota allocations assigned to a tenant. Callers may only list their own tenant.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, ListTenantStorageSetResponse)

Example

{
   "storagesets" : [
      {
         "quota_bytes" : 2199023255552,
         "storageset_id" : 1,
         "storageset_name" : "Set 1"
      },
      {
         "quota_bytes" : 5497558138880,
         "storageset_id" : 3,
         "storageset_name" : "Set 3"
      }
   ],
   "total" : 2
}

GET /api/v1/tenants/{tenant_id}/storagesets/{storageset_id}

Get tenant storageset

Returns a single storageset quota allocation for a tenant. Callers may only access their own tenant.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, GetTenantStorageSetResponse)

Example

{
   "storageset" : {
      "quota_bytes" : 2199023255552,
      "storageset_id" : 1,
      "storageset_name" : "Set 1"
   }
}

PUT /api/v1/tenants/{tenant_id}/storagesets/{storageset_id}

Assign or resize tenant storageset

Upserts a storageset quota allocation for a tenant: assigns the storageset with the given quota if it is not yet assigned, or replaces the quota if it already is. The combined cross-tenant quota must fit within the storageset capacity. Only platform-admin and storage-admin may change tenant storageset quotas, for any tenant; a Tenant Admin gets 403.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Request Body (application/json, required)

Schema: TenantStorageSetQuotaRequest

Request body for assigning or resizing a tenant storageset quota.

Example

{
   "quota_bytes" : 2199023255552
}

Responses

Response Body (200, GetTenantStorageSetResponse)

Example

{
   "storageset" : {
      "quota_bytes" : 2199023255552,
      "storageset_id" : 1,
      "storageset_name" : "Set 1"
   }
}

DELETE /api/v1/tenants/{tenant_id}/storagesets/{storageset_id}

Unassign tenant storageset

Unassigns a storageset from a tenant. Callers may only modify their own tenant.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses