> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/organizations-and-access/organizations.md). # Organization overview Kangal uses the tenant as its primary customer and data-isolation boundary. The console presents the signed-in tenant as an organization. Workspaces and RBAC organization/team records add structure inside that boundary; they do not allow a regular administrator to cross into another tenant. ## Scope model | Object | Purpose | Isolation behavior | | ----------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | Tenant | Customer organization and top-level authorization scope | A regular admin is fixed to one tenant. | | Child tenant | Optional delegated organization below a parent tenant | Parent admins can list and read direct children when tenant-creation policy permits them. | | Workspace | Named grouping for gateway and integration scope | Always belongs to one tenant; names are unique only inside that tenant. | | RBAC organization | Optional governance record inside a tenant | Does not replace the tenant or create a second isolation boundary. | | Team | Tenant-scoped member and role-reference collection | Organizes members and governance references; see [Members and RBAC](/organizations-and-access/members-rbac.md). | Gateway creation also generates gateway workspace metadata. Treat a separately created workspace record and a gateway's generated workspace metadata as distinct tenant-scoped records unless the resource explicitly references the workspace ID. ## Organization console workflow Open `//dashboard/admin/organizations`. The page resolves the organization from `GET /tenants/current` and provides: * **Teams**: create, edit, delete, and maintain member ID and role references. * **Users**: list tenant users and their direct account roles. * **Settings**: inspect the organization name, status, and tenant slug. * Links to **Roles and access**, **SSO and provisioning**, and the plan view. The tenant slug is the organization ID used in API scope fields. Treat it as a stable identifier even when the display name changes. ## Tenant behavior Regular admins can read their own tenant and direct child tenants. Listing tenants automatically filters to children of the caller's tenant. Super-admins can list all tenants, filter by `parent_slug`, deactivate or delete a tenant, and start a short-lived audited impersonation session. Creating a child tenant requires both `can_create_tenant` on the caller and remaining `tenant_quota`. Slugs are globally unique, even though the create API also checks the requested parent. Deactivation marks the tenant inactive. It is not a cascade-delete workflow; review users, sessions, integrations, and retained data separately. Tenant deletion is restricted to super-admin and removes the tenant record, not a documented cascade of every tenant-owned resource. ## Workspaces Use the Admin Workspace API to create and maintain workspace records. ```bash export KANGAL_URL='https://api.example.com' export KANGAL_API_TOKEN='' curl --request POST "$KANGAL_URL/admin/workspaces" \ --header "Authorization: Bearer $KANGAL_API_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "tenant_id": "acme", "name": "payments", "description": "Payment APIs", "labels": {"team": "platform"}, "metadata": {"cost_center": "cc-100"} }' ``` List calls support `skip` and `limit` (`1` to `200`) and return the total in `X-Total-Count`: ```bash curl --include "$KANGAL_URL/admin/workspaces?skip=0&limit=100" \ --header "Authorization: Bearer $KANGAL_API_TOKEN" ``` Use `PATCH /admin/workspaces/{workspace_id}` to change `name`, `description`, `labels`, or `metadata`. Tenant ID and creation time cannot be moved by an update. Create, update, and delete operations are audit logged with the workspace ID. ## RBAC organization records Most customers can use the tenant shown in the console without creating an extra RBAC organization record. Create one only when a governance tool needs a named organizational container for teams. ```bash curl --request POST "$KANGAL_URL/admin/rbac/organizations" \ --header "Authorization: Bearer $KANGAL_API_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "tenant_id": "acme", "name": "Platform Engineering", "description": "Central API platform team" }' ``` Organization, team, and workspace list responses remain tenant filtered for a regular admin even if a different `tenant_id` is requested. Cross-tenant detail lookups return `404` or `403` depending on the endpoint so data is not exposed. ## Common workflows ### Onboard a new business unit 1. Decide whether it needs hard isolation. Use a separate tenant for hard isolation; use a workspace or team for structure inside the same tenant. 2. If using a child tenant, confirm the parent admin's creation permission and quota. 3. Create tenant users through an invitation, SSO/JIT, SCIM, or an authorized admin API. 4. Create workspaces and teams as needed. 5. Assign direct roles and verify access with a non-privileged test account. ## Troubleshooting | Symptom | Check | | --------------------------------------- | --------------------------------------------------------------------------------------------------- | | `400 tenant_id is required` | A tenantless super-admin must select a tenant for detail or write operations. | | `403 Cannot access another tenant` | The user or token is tenant-scoped; remove the foreign tenant value. | | Detail returns `404` for a known ID | Confirm the resource belongs to the caller's tenant. Cross-tenant records are intentionally hidden. | | Workspace create says the name exists | Workspace names must be unique within the tenant. | | Team create says organization not found | The optional RBAC organization ID must belong to the same tenant. | | Child tenant create is denied | Check `can_create_tenant` and `tenant_quota`. | | Deactivated tenant still has records | Deactivation is a status change, not a cascade cleanup. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kangal.dev/organizations-and-access/organizations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.