Skip to main content
POST
/
v1
/
tenants
Create tenant
curl --request POST \
  --url https://api.example.com/v1/tenants \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "slug": "<string>",
  "ownerEmail": "<string>",
  "plan": "<string>",
  "settings": {
    "settings.awsRoleArn": "<string>",
    "settings.awsExternalId": "<string>",
    "settings.awsRegion": "<string>"
  }
}
'

​
Overview

Creates a new tenant (organization) in CauseFlow. Each tenant is an isolated workspace with its own users, incidents, and configuration. Required role: admin

​
Request body

​
name
string
required
The display name of the tenant. Used in the dashboard and notifications. Example: "Acme Corp".
​
slug
string
required
A URL-safe identifier for the tenant. Must be lowercase alphanumeric characters and hyphens only. Example: "acme-corp". Must be globally unique — returns 409 Conflict if already taken.
​
ownerEmail
string
required
Email address of the tenant owner. Must be a valid email address. The owner receives an invitation to activate their account.
​
plan
string
The subscription plan for the tenant. One of: starter, pro, business, enterprise. Defaults to starter if not specified.
​
settings
object
Optional AWS integration settings for the tenant.

​
Response

Returns 201 Created with the newly created tenant. 
{
  "tenantId": "ten_EXAMPLE_01HX9VTPQR3KF8MZ",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "status": "active",
  "plan": "starter",
  "createdAt": "2026-04-01T12:00:00Z"
}
FieldTypeDescription
tenantIdstringUnique identifier for the newly created tenant
namestringThe tenant display name
slugstringThe URL-safe tenant identifier
statusstringAlways "active" for newly created tenants
planstringThe subscription plan
createdAtstringISO 8601 timestamp of when the tenant was created

​
Error responses

StatusError codeDescription
400validation_errorA required field is missing or fails validation
409slug_conflictA tenant with the provided slug already exists

​
Examples

curl https://api.causeflow.ai/v1/tenants \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp",
    "ownerEmail": "owner@acme.com",
    "plan": "pro",
    "settings": {
      "awsRoleArn": "arn:aws:iam::<your-aws-account-id>:role/CauseFlowRole",
      "awsExternalId": "causeflow-ext-id-acme",
      "awsRegion": "us-east-1"
    }
  }'