> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crovver.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Tenant

> Create a new B2B tenant (workspace).

Creates a new billing tenant in Crovver. For **B2B orgs**, call this when a new workspace/organization is created in your app. For **D2C**, tenants are auto-created on first checkout — this endpoint is not needed.

## Request Body

<ParamField body="externalTenantId" type="string" required>
  The workspace/org ID from your application
</ParamField>

<ParamField body="name" type="string" required>
  Display name for the tenant
</ParamField>

<ParamField body="externalUserId" type="string" required>
  The external user ID of the billing owner
</ParamField>

<ParamField body="ownerEmail" type="string">
  Email address of the billing owner
</ParamField>

<ParamField body="ownerName" type="string">
  Display name of the billing owner
</ParamField>

<ParamField body="slug" type="string">
  URL-friendly slug. Auto-generated from `name` if not provided.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs stored on the tenant.
</ParamField>

## Authentication

Requires a **secret key** (`Authorization: Bearer sk_live_...`). Restricted to B2B organizations.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.crovver.com/api/public/tenants" \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "externalTenantId": "workspace_abc123",
      "name": "Acme Corp",
      "externalUserId": "user_123",
      "ownerEmail": "admin@acme.com",
      "ownerName": "Jane Smith"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "data": {
      "tenant": {
        "id": "uuid",
        "externalTenantId": "workspace_abc123",
        "name": "Acme Corp",
        "slug": "acme-corp",
        "isActive": true,
        "createdAt": "2025-01-01T00:00:00Z"
      },
      "owner": {
        "id": "uuid",
        "externalUserId": "user_123",
        "email": "admin@acme.com",
        "name": "Jane Smith"
      },
      "message": "Tenant created successfully"
    }
  }
  ```

  ```json 403 D2C organization theme={null}
  {
    "success": false,
    "error": "This endpoint is restricted to B2B organizations."
  }
  ```

  ```json 409 Duplicate theme={null}
  {
    "success": false,
    "error": "Tenant ID or Slug already exists"
  }
  ```
</ResponseExample>