Tenant creation

This recipe shows how to create a new tenant in your organization. Tenant creation is restricted to organization-level administrators and is typically used during onboarding of new business units, subsidiaries, or external clients.

Endpoint

POST /v1/tenants

Creates a new tenant with the specified settings. The new tenant is initialized with the default subscription tier, an empty ledger of truth, and the creator as the initial admin.

Prerequisites

• A valid orgId and bearer JWT.
• The user must have the org_admin role.
• Idempotency key is required.

Request body

curl -X POST https://api.falconveritas.com/v1/tenants \
  -H "Authorization: Bearer $FVI_JWT" \
  -H "X-FVI-Org-Id: $FVI_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "acme-bank-uk",
    "display_name": "Acme Bank UK",
    "default_currency": "GBP",
    "time_zone": "Europe/London",
    "locale": "en-GB",
    "subscription_tier": "enterprise",
    "region": "uk",
    "data_residency": "uk",
    "admin": {
      "email": "alice.admin@acmebank.co.uk",
      "name": "Alice Anderson",
      "send_invitation": true
    },
    "settings": {
      "auto_match_threshold": 0.92,
      "analyst_review_threshold": 0.70,
      "sla_minutes": 240,
      "evidence_retention_days": 2555
    },
    "idempotency_key": "tenant-fvi-$RANDOM"
  }'

Response

{
  "id": "d5e9a8e1-3b3e-4d2e-9b9c-3a2e9b1f4d5b",
  "slug": "acme-bank-uk",
  "display_name": "Acme Bank UK",
  "default_currency": "GBP",
  "time_zone": "Europe/London",
  "locale": "en-GB",
  "subscription_tier": "enterprise",
  "region": "uk",
  "data_residency": "uk",
  "status": "active",
  "created_at": "2026-08-22T17:00:00Z",
  "created_by": "user:admin",
  "initial_admin": {
    "email": "alice.admin@acmebank.co.uk",
    "invitation_sent": true,
    "invitation_link": "https://app.falconveritas.com/invite/xyz123"
  }
}

Settings reference

Setting	Default	Description
auto_match_threshold	0.92	Confidence above this triggers automatic match
analyst_review_threshold	0.70	Confidence between this and auto-match triggers analyst review
sla_minutes	240	Default SLA for exception resolution (4 hours)
evidence_retention_days	2555	Evidence pack retention (7 years for financial compliance)

Data residency

FVI supports per-tenant data residency for regulatory compliance:

Region	Residency	Cloud
US	us-east-1, us-west-2	AWS
EU	eu-west-1, eu-central-1	AWS
UK	eu-west-2	AWS
APAC	ap-southeast-1, ap-northeast-1	AWS
Custom	Customer-controlled	Multi-cloud

Use cases

• Onboarding new subsidiary — create a tenant for a new legal entity with the same corporate branding.
• Multi-tenant SaaS — create tenants for new external clients of your platform.
• Sandbox tenants — create sandbox tenants for testing without affecting production.
• Geographic expansion — create a tenant with appropriate data residency for a new region.

Code samples

TypeScript

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

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

const tenant = await fvi.tenants.create({
  slug: 'acme-bank-uk',
  displayName: 'Acme Bank UK',
  defaultCurrency: 'GBP',
  timeZone: 'Europe/London',
  subscriptionTier: 'enterprise',
  region: 'uk',
  dataResidency: 'uk',
  admin: {
    email: 'alice.admin@acmebank.co.uk',
    name: 'Alice Anderson',
    sendInvitation: true,
  },
  idempotencyKey: `tenant-fvi-${Date.now()}`,
});

console.log('Tenant created:', tenant.id);
console.log('Invitation link:', tenant.initial_admin.invitation_link);

Python

from falconveritas import FVI

client = FVI(
  bearer=os.environ["FVI_JWT"],
  org_id=os.environ["FVI_ORG_ID"],
)

tenant = client.tenants.create(
  slug="acme-bank-uk",
  display_name="Acme Bank UK",
  default_currency="GBP",
  time_zone="Europe/London",
  subscription_tier="enterprise",
  region="uk",
  data_residency="uk",
  admin={
    "email": "alice.admin@acmebank.co.uk",
    "name": "Alice Anderson",
    "send_invitation": True,
  },
  idempotency_key=f"tenant-fvi-{int(time.time())}",
)
print("Tenant created:", tenant.id)
print("Invitation link:", tenant.initial_admin.invitation_link)

Related articles

• List tenants
• Role management
• OAuth client setup
• Tenant settings

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