Organizations

Multi-tenant organization management with Keycloak realm isolation, default group provisioning, and OpenFGA permission bootstrapping.

Organizations

Organizations are the top-level tenant boundary in CRAFT. Each organization maps 1:1 to a Keycloak realm, providing full identity isolation between tenants. When you create an organization, the platform provisions a complete identity and authorization environment automatically.

Every resource in the platform is scoped to an organization via organization_id. The org ID is never supplied by the client in request bodies — it is always extracted from the JWT token’s issuer claim, which identifies the Keycloak realm.

How Organizations Work

Creating an organization triggers a coordinated setup across three systems:

1. Keycloak Realm Creation

   A new Keycloak realm is created using the organization ID as the realm name. This realm holds all users, groups, and identity provider configurations for the tenant.

2. Default Group Provisioning

   Default groups are created within the realm to establish the role hierarchy:

   • org-owners — Full organization control
   • org-admins — Administrative access (user and project management)
   • org-members — Standard membership with read access

   A groups mapper is configured so group memberships appear as claims in JWT tokens.

3. OpenFGA Permission Setup

   Permission tuples are written to OpenFGA mapping each group to its corresponding relation:

   • org-owners -> owner relation on the organization
   • org-admins -> admin relation on the organization
   • org-members -> member relation on the organization

   This means any user added to org-admins in Keycloak automatically inherits admin permissions across the platform.

4. Database Record

   An organization record is created in the Governance database with the org ID, name, description, and timestamps.

Organization ID in JWT

The organization ID is derived from the Keycloak realm embedded in the token’s iss (issuer) claim. When a user authenticates against a realm, the platform extracts the realm name as the org_id:

Token issuer: https://keycloak.example.com/realms/acme-corp
                                                  ^^^^^^^^^ org_id = "acme-corp"

This design means:

• The org_id is cryptographically bound to the token (it comes from the issuer verified by JWKS signature)
• Clients cannot forge or override the organization context
• Users in the master realm (platform developers) have org_id = null

API Reference

The Organizations API is part of the Governance service (port 8001).

POST /governance/organizations

Creates a new organization with Keycloak realm, default groups, and OpenFGA permissions.

Access: Platform developers only (master realm)

Request Body

{
  "id": "acme-corp",
  "name": "Acme Corporation",
  "description": "Production tenant for Acme Corp",
  "create_users": true
}

The id must follow Keycloak realm naming rules: alphanumeric characters, hyphens, and underscores only.

When create_users is true, default users are created and added to the appropriate groups for immediate access.

Response (201 Created)

{
  "id": "acme-corp",
  "name": "Acme Corporation",
  "description": "Production tenant for Acme Corp",
  "created_at": "2026-04-01T12:00:00Z"
}

GET /governance/organizations/{org_id}

Retrieves organization details by ID.

Access: Users with can_read permission on the organization (owners, admins, or members).

Response (200 OK)

{
  "id": "acme-corp",
  "name": "Acme Corporation",
  "description": "Production tenant for Acme Corp",
  "created_at": "2026-04-01T12:00:00Z",
  "updated_at": "2026-04-02T08:30:00Z"
}

DELETE /governance/organizations/{org_id}

Deletes an organization and cascades to all its projects. Removes OpenFGA permission tuples, the Keycloak realm (including all users and groups), and database records.

Access: Platform developers only (master realm). Idempotent: returns 204 whether the organization was deleted or was already absent.

Bootstrap Organization

During first startup, the Governance service automatically bootstraps a default organization:

bootstrap:
  organization:
    id: "emergence"
    name: "Emergence"
    description: "Emergence organization"
    create_admin_user: true

When create_admin_user is true (the default), a user named emergence is created with:

• Username: emergence
• Password: emergence (change immediately in production)
• Group: org-admins
• OpenFGA relation: admin on the organization

The bootstrap admin user is intended for development and initial setup. Always change the default password in production environments.

Organization Permissions

Organizations define the following computed permissions in the OpenFGA schema:

Permission	Owner	Admin	Member
can_read	Yes	Yes	Yes
can_write	Yes	—	—
can_delete	Yes	—	—
can_manage_projects	Yes	Yes	—
can_manage_users	Yes	Yes	—
can_read_secrets	Yes	Yes	Yes
can_manage_secrets	Yes	Yes	—
can_read_metadata	Yes	Yes	Yes
can_manage_metadata	Yes	Yes	—

Next Steps

Projects

Learn how projects scope resources within organizations.

Multi-Tenancy

Understand the full tenant isolation architecture.

Authentication

See how Keycloak realms power the authentication flow.

Authorization

Explore the OpenFGA permission model in depth.