Organizations

Organizations are the top-level resource in HatiData. Every user, environment, policy, and API key belongs to an organization.

Create Organization

POST /v1/organizations

Creates a new organization. The authenticated user becomes the Owner.

Request:

curl -X POST https://api.hatidata.com/v1/organizations \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp",
    "billing_email": "billing@acme.com",
    "cloud_region": "us-east-1",
    "settings": {
      "mfa_required": false,
      "enforce_sso": false
    }
  }'

Response 201 Created:

{
  "org_id": "org_a1b2c3d4",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "billing_email": "billing@acme.com",
  "cloud_region": "us-east-1",
  "tier": "free",
  "status": "active",
  "settings": {
    "mfa_required": false,
    "enforce_sso": false
  },
  "created_at": "2026-02-16T10:00:00Z",
  "updated_at": "2026-02-16T10:00:00Z"
}

Field	Type	Required	Description
name	string	Yes	Display name
slug	string	Yes	URL-safe identifier (unique)
billing_email	string	Yes	Email for billing notifications
cloud_region	string	No	Deployment region (default: us-east-1)
settings	object	No	Organization-level settings

Get Organization

GET /v1/organizations/{org_id}

Retrieves organization details. Requires membership in the organization.

Request:

curl https://api.hatidata.com/v1/organizations/org_a1b2c3d4 \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "org_id": "org_a1b2c3d4",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "billing_email": "billing@acme.com",
  "cloud_region": "us-east-1",
  "tier": "cloud",
  "status": "active",
  "stripe_customer_id": "cus_abc123",
  "stripe_subscription_id": "sub_xyz789",
  "settings": {
    "mfa_required": true,
    "enforce_sso": true,
    "sso_provider": "okta"
  },
  "quotas": {
    "monthly_credit_limit": 10000,
    "used": 3250,
    "max_concurrent_queries": 100,
    "storage_limit_gb": 500
  },
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-02-10T14:30:00Z"
}

Organization Status Values

Status	Description
active	Organization is fully operational
pending_payment	Awaiting Stripe checkout completion
provisioning	Cloud infrastructure being deployed
suspended	Suspended due to billing or policy violation
cancelled	Subscription cancelled, data retention in effect

Update Organization

PUT /v1/organizations/{org_id}

Updates organization settings. Requires Owner or Admin role.

Request:

curl -X PUT https://api.hatidata.com/v1/organizations/org_a1b2c3d4 \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "billing_email": "finance@acme.com",
    "settings": {
      "mfa_required": true,
      "enforce_sso": true
    }
  }'

Response 200 OK:

{
  "org_id": "org_a1b2c3d4",
  "name": "Acme Corporation",
  "slug": "acme-corp",
  "billing_email": "finance@acme.com",
  "cloud_region": "us-east-1",
  "tier": "cloud",
  "status": "active",
  "settings": {
    "mfa_required": true,
    "enforce_sso": true,
    "sso_provider": "okta"
  },
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-02-16T11:00:00Z"
}

Field	Type	Description
name	string	Updated display name
billing_email	string	Updated billing email
settings.mfa_required	boolean	Enforce MFA for all users
settings.enforce_sso	boolean	Require SSO login (disables password auth)

Immutable Fields

The slug and cloud_region fields cannot be changed after creation. To change regions, create a new organization and migrate data.

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Missing required fields or invalid format
401	UNAUTHORIZED	Missing or invalid authentication
403	FORBIDDEN	Insufficient role (must be Owner or Admin for updates)
404	NOT_FOUND	Organization does not exist
409	CONFLICT	Slug already in use