Skip to main content

List tenants

This recipe shows how to list all tenants visible to your user via the FVI API. Use this endpoint to power tenant pickers, switcher UIs, or organizational overview dashboards.

Endpoint​

GET /v1/tenants

Returns an array of tenant summaries with the tenant UUID, display name, slug, default currency, time zone, and the user's role within the tenant.

Prerequisites​

  • A valid tenantId and either a publishable key, a JWT issued by Supabase Auth (HS256 or RS256), or a service-role key with a justified call-site.
  • The user must be a member of at least one tenant.
  • For cross-tenant listings (enterprise admin), the user must have the org_admin role.

Request​

curl -X GET https://api.falconveritas.com/v1/tenants \
  -H "Authorization: Bearer $FVI_JWT" \
  -H "X-FVI-Org-Id: $FVI_ORG_ID" \
  -H "Content-Type: application/json"

Response​

{
  "items": [
    {
      "id": "f1a4e6e2-4b3e-4d2e-9b9c-3a2e9b1f4d5a",
      "slug": "acme-bank",
      "display_name": "Acme Bank",
      "default_currency": "USD",
      "time_zone": "America/New_York",
      "role": "tenant_admin",
      "created_at": "2026-08-01T12:00:00Z",
      "subscription_tier": "enterprise"
    },
    {
      "id": "d5e9a8e1-3b3e-4d2e-9b9c-3a2e9b1f4d5b",
      "slug": "acme-bank-uk",
      "display_name": "Acme Bank UK",
      "default_currency": "GBP",
      "time_zone": "Europe/London",
      "role": "tenant_admin",
      "created_at": "2026-08-15T08:30:00Z",
      "subscription_tier": "enterprise"
    }
  ],
  "next_cursor": null
}

Filter parameters​

The endpoint supports the following query parameters:

ParameterTypeDescription
limitinteger (1-200, default 50)Maximum number of tenants to return
cursorstringPagination cursor from the previous response
rolestringFilter by the user's role within the tenant
subscription_tierstringFilter by subscription tier (free, pro, enterprise)

Use cases​

  • Tenant switcher UI — populate the dropdown of available tenants.
  • Admin dashboard — show all tenants in the user's organization.
  • Audit tooling — list all tenants for periodic access reviews.

Code samples​

TypeScript​

import { FVI } from '@falconveritas/sdk';

const fvi = new FVI({
  baseUrl: 'https://api.falconveritas.com',
  bearer: process.env.FVI_JWT!,
  tenantId: process.env.FVI_TENANT_ID!,
});

const tenants = await fvi.tenants.list({ limit: 100 });
for (const tenant of tenants.items) {
  console.log(`${tenant.display_name} (${tenant.role})`);
}

Python​

from falconveritas import FVI

client = FVI(
  bearer=os.environ["FVI_JWT"],
  tenant_id=os.environ["FVI_TENANT_ID"],
)

tenants = client.tenants.list(limit=100)
for tenant in tenants.items:
  print(f"{tenant.display_name} ({tenant.role})")

Last updated: 2026-08-22 · Page owner: Documentation · Source: src/lib/api/tenants.ts.