Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ivory.finance/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

POST /v1/admin/tenants kicks off the full 9-step provisioning pipeline as an async background task. The endpoint returns immediately with a provisioning state and a poll URL to track progress.
This endpoint is restricted to the admin Kong consumer via ACL. It is never exposed to client tenants.

​
Provisioning pipeline

StepAction
1Create tenant database environment
2Wait until tenant environment is healthy; fetch API keys
3Run tenant migrations (IAM schema, SoD rules, workflow templates)
4Verify seed data (roles, rules, templates counts)
5Invite admin user — sends an invitation email to admin_email
6Create private FalkorDB graph (client_{slug})
7Create per-tenant OpenSearch knn index + alias
8Invalidate TenantMiddleware Valkey cache
9Optional Stripe billing → set is_active = TRUE → publish iam:tenants:provisioned stream event
Track progress via GET /v1/admin/tenants/{slug}/status.

​
Idempotency

Existing stateBehaviour
active409 Conflict — tenant already live
provisioning202 — returns existing poll URL, no duplicate task spawned
failed202 — resumes from last completed step
Not found202 — inserts stub row, starts from step 1

​
Request

​
slug
string
required
URL-safe tenant identifier. Must match /^[a-z0-9-]{3,48}$/ — lowercase letters, digits, and hyphens only. Becomes the tenant’s subdomain prefix and internal identifier.
​
display_name
string
required
Human-readable tenant name shown in dashboards and billing.
​
region
string
required
Data residency region. One of: us-east-1 · eu-central-1 · ap-southeast-1
​
tier
string
default:"enterprise"
Billing tier. One of: pilot · enterprise · enterprise_plus
TierStripe
pilotNo subscription
enterpriseSubscription created
enterprise_plusSubscription created
​
admin_email
string
required
Email address of the tenant admin. Receives an invitation email at step 5.
​
data_residency_verified
boolean
required
Must be true. Confirms that data residency requirements for the chosen region have been verified before provisioning begins.

​
Response

​
tenant_id
string
UUID of the newly created tenant row in control.tenants.
​
slug
string
The tenant slug as provided.
​
provisioning_state
string
Always provisioning on a 202 response.
​
poll_url
string
Relative path to poll provisioning progress: /v1/admin/tenants/{slug}/status

​
Examples

curl -X POST https://api.ivory.finance/v1/admin/tenants \
  -H "X-API-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "acme-bank",
    "display_name": "Acme Bank",
    "region": "us-east-1",
    "tier": "enterprise",
    "admin_email": "admin@acmebank.com",
    "data_residency_verified": true
  }'
Response: 
{
  "tenant_id":          "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "slug":               "acme-bank",
  "provisioning_state": "provisioning",
  "poll_url":           "/v1/admin/tenants/acme-bank/status"
}

​
Error responses

CodeReason
409Tenant with this slug is already active
422Validation error — invalid slug format, invalid region/tier, or data_residency_verified is false