Organizations API

Organizations are the top-level entity in Forgexa's multi-tenant architecture. An organization contains workspaces, manages members, enforces budgets, and defines shared configurations (integrations, workflow templates, runtimes).

Hierarchy: Organization → Workspace → Project → Requirement → Execution

Create Organization

Any authenticated user can create an organization and become its owner.

POST /api/v1/organizations
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Acme Corp",
  "description": "Product engineering division"
}

Response 201 Created

{
  "id": "uuid",
  "name": "Acme Corp",
  "org_key": "acme-corp",
  "slug": "acme-corp",
  "owner_id": "uuid",
  "description": "Product engineering division",
  "logo_url": null,
  "settings": {},
  "budget_monthly_limit_usd": null,
  "budget_used_usd": 0.0,
  "budget_alert_threshold": 0.80,
  "registration_mode": "invite-only",
  "max_workspaces": null,
  "max_members": null,
  "member_count": 1,
  "workspace_count": 0,
  "created_at": "2026-05-16T00:00:00Z",
  "updated_at": "2026-05-16T00:00:00Z"
}

List Organizations

Returns all organizations the current user is a member of.

GET /api/v1/organizations
Authorization: Bearer <token>

Response 200 OK

[
  {
    "id": "uuid",
    "name": "Acme Corp",
    "org_key": "acme-corp",
    "slug": "acme-corp",
    "owner_id": "uuid",
    "member_count": 5,
    "workspace_count": 3,
    "created_at": "2026-01-01T00:00:00Z"
  }
]

Get Organization

Requires member role or higher.

GET /api/v1/organizations/{org_id}
Authorization: Bearer <token>

Update Organization

Requires admin role or higher.

PUT /api/v1/organizations/{org_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Acme Corp Engineering",
  "description": "Updated description",
  "registration_mode": "invite-only",
  "max_workspaces": 10,
  "max_members": 50,
  "budget_monthly_limit_usd": 2000,
  "budget_alert_threshold": 0.85
}

Updatable Fields

Field	Type	Description
name	string	Organization display name
description	string	Brief description
logo_url	string	Logo image URL
settings	object	Custom settings (JSON)
registration_mode	string	open or invite-only (default: invite-only)
max_workspaces	int	Maximum workspaces (null = unlimited)
max_members	int	Maximum members (null = unlimited)
budget_monthly_limit_usd	float	Monthly spending cap (null = unlimited)
budget_alert_threshold	float	Alert when usage exceeds this ratio (default 0.80)

Delete Organization

Requires owner role. Cascades to all workspaces, projects, and data within the organization.

DELETE /api/v1/organizations/{org_id}
Authorization: Bearer <token>

Response 204 No Content

WARNING

Deleting an organization permanently removes all its workspaces, projects, requirements, executions, and related data. This action cannot be undone.

List Organization Workspaces

Returns all workspaces within the organization.

GET /api/v1/organizations/{org_id}/workspaces
Authorization: Bearer <token>

Response 200 OK

[
  {
    "id": "uuid",
    "name": "Backend Team",
    "workspace_key": "backend-team",
    "organization_id": "uuid",
    "owner_id": "uuid",
    "budget_monthly_limit_usd": 500.0,
    "created_at": "2026-01-01T00:00:00Z"
  }
]

Members

Get My Role

Lightweight endpoint to check the current user's role in the organization (used by frontend navigation).

GET /api/v1/organizations/{org_id}/my-role
Authorization: Bearer <token>

Response 200 OK

{
  "role": "admin"
}

List Members

GET /api/v1/organizations/{org_id}/members
Authorization: Bearer <token>

Response 200 OK

[
  {
    "organization_id": "uuid",
    "user_id": "uuid",
    "role": "owner",
    "user_name": "Alice Chen",
    "user_email": "alice@acme.com",
    "user_avatar_url": "/api/v1/users/uuid/avatar",
    "joined_at": "2026-01-01T00:00:00Z"
  }
]

Add Member

Requires admin role. Add a user by email or user ID.

POST /api/v1/organizations/{org_id}/members
Authorization: Bearer <token>
Content-Type: application/json

{
  "email": "bob@acme.com",
  "role": "member"
}

Response 201 Created

Field	Type	Description
email	string	User email (mutually exclusive with user_id)
user_id	UUID	User ID (mutually exclusive with email)
role	string	admin or member (cannot assign owner)

Update Member Role

Requires admin role. Only the owner can promote/demote admins.

PUT /api/v1/organizations/{org_id}/members/{member_user_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "role": "admin"
}

Remove Member

Requires admin role. Owners cannot be removed (use ownership transfer).

DELETE /api/v1/organizations/{org_id}/members/{member_user_id}
Authorization: Bearer <token>

Response 204 No Content

Transfer Ownership

Only the current owner can transfer ownership to an existing member.

POST /api/v1/organizations/{org_id}/transfer-ownership
Authorization: Bearer <token>
Content-Type: application/json

{
  "new_owner_id": "uuid"
}

Workflow Template

Organization-level default workflow template applied to new workspaces/projects.

Get Template

GET /api/v1/organizations/{org_id}/workflow-template
Authorization: Bearer <token>

Response 200 OK

{
  "template": "# WORKFLOW.md\norchestration:\n  mode: polling\n..."
}

Set Template

Requires admin role.

PUT /api/v1/organizations/{org_id}/workflow-template
Authorization: Bearer <token>
Content-Type: application/json

{
  "template": "# WORKFLOW.md\norchestration:\n  mode: polling\nagents:\n  - claude-code\n  - codex\n"
}

Budget

Get Organization Budget

Requires admin role. Returns aggregate budget across all workspaces.

GET /api/v1/organizations/{org_id}/budget
Authorization: Bearer <token>

Response 200 OK

{
  "budget_monthly_limit_usd": 2000.0,
  "budget_used_usd": 450.75,
  "budget_alert_threshold": 0.80,
  "usage_percent": 0.225,
  "workspaces_total_used_usd": 450.75,
  "workspaces_total_limit_usd": 1500.0,
  "workspaces": [
    {
      "workspace_id": "uuid",
      "workspace_name": "Backend Team",
      "budget_monthly_limit_usd": 500.0,
      "budget_used_usd": 127.45,
      "budget_alert_threshold": 0.80,
      "usage_percent": 0.255
    }
  ]
}

Audit Logs

Requires admin role. Returns paginated audit log entries scoped to the organization.

GET /api/v1/organizations/{org_id}/audit-logs?page=1&page_size=20
Authorization: Bearer <token>

Query Parameters

Parameter	Type	Description
action	string	Filter by action (e.g. member.added)
actor_id	UUID	Filter by actor
start_date	datetime	Start of date range (ISO 8601)
end_date	datetime	End of date range (ISO 8601)
page	int	Page number (default 1)
page_size	int	Items per page (default 20)

Response 200 OK

{
  "total": 85,
  "page": 1,
  "page_size": 20,
  "items": [
    {
      "id": "uuid",
      "organization_id": "uuid",
      "workspace_id": "uuid",
      "workspace_name": "Backend Team",
      "actor_type": "human",
      "actor_id": "uuid",
      "actor_name": "Alice Chen",
      "action": "member.added",
      "resource_type": "organization_member",
      "resource_id": "uuid",
      "detail": "Added bob@acme.com as member",
      "ip_address": "192.168.1.100",
      "created_at": "2026-05-16T10:30:00Z"
    }
  ]
}

Runtimes

List Organization Runtimes

Returns runtime daemons shared across the organization.

GET /api/v1/organizations/{org_id}/runtimes
Authorization: Bearer <token>

Response 200 OK

[
  {
    "id": "uuid",
    "name": "dev-machine-01",
    "hostname": "dev-01.internal",
    "status": "online",
    "agents": ["claude-code", "codex"],
    "last_heartbeat": "2026-05-16T10:29:00Z",
    "owner_id": "uuid",
    "owner_name": "Alice Chen"
  }
]

Role Hierarchy

Organization roles control access across the organization:

Role	Description
owner	Full control. Can delete org, transfer ownership. One per org.
admin	Manage members, integrations, budgets, audit logs, templates.
member	View members, workspaces, runtimes, templates. Create workspaces.

Org admin roles cascade to workspace roles — an org admin automatically has admin access to all workspaces within the organization.