Departments and projects
Below the organization, Wexa has exactly two structural levels: departments and projects. Mirroring a company means deciding, for each team, which of the two it should be. This page gives that decision a rule, then covers the screens that create each.
The rule
A project is the unit of isolation. A department is the unit of delegated administration.
Everything a team's work consists of — its context graph, its knowledge base, its data catalog, its ontology, its agents and their executions — belongs to exactly one project and is not visible from another. If two teams must not see each other's material, they need two projects; nothing weaker will do it.
A department owns no work of its own. What it owns is who administers what: a department administrator administers every project underneath it without being named on each one, and a department carries an allow-list of what its projects may reach. If you have one team whose work is one body of material, you want one project — putting a department around it buys nothing. If you have a division with five teams whose work must stay separate but whose administration should be one person's job, you want a department with five projects.
Worked cases
| Your situation | What to create | Why |
|---|---|---|
| A single team trying Wexa out | One project, no department | A department with one project adds a level that never branches |
| Two teams who must not see each other's data | Two projects | Isolation is a property of the project and only of the project |
| Two teams who share data freely and share a lead | One project | A second project means copying or re-ingesting everything they share |
| A division of several teams, one divisional lead who should administer all of them | One department, one project per team | The lead is made a department administrator once instead of on every project |
| The same work at different stages, e.g. a trial before a rollout | Two projects | The trial's context and ontology should not survive into the rollout |
| A team that needs a different set of connectors or models from its neighbours | One project, and a department scope that permits only what it needs | Scopes are set on the department and narrowed per project |
The trap to avoid is creating a department per team and a project per team. That leaves a one-to-one tree where every administrative act has to be done at the level you happened to guess, and it is the shape that is hardest to collapse later.
Departments
Settings → Departments (/settings/departments). Departments are also served by the identity
service at /departments and /settings/departments.
Creating one. The screen asks for a name and nothing else. A duplicate name is refused with
409 "A department with that name already exists."
Who may create one. Organization-wide administrators only — an Org Admin or the organization's
owner. A department administrator administers the department they were given; creating further ones
is an organization-level act, and both POST /departments and POST /settings/departments answer
403 "Only a super admin or org admin can create a department." to anyone below that tier. The
"New department" button is hidden for them for the same reason.
Renaming one. Safe: people and projects stay attached. The screen says as much.
Deleting one. Refused with 409 while it still has people — "Cannot delete a department with N member(s)." Move the people first.
Who may change one. PUT and DELETE are reserved for organization-wide administrators, the
department's own owner, and its own administrators. A department administrator scoped to a different
department gets 403 "You can only manage departments you administer." This is enforced on the
server, not only hidden in the screen.
Department scopes
Open a department (/settings/departments/{id}) and you can set its scopes — which projects it
reaches, and which modules, connectors, models, entity types and actions its work may use, plus a
clearance for sensitive data classes.
Two properties make this predictable:
- Restrict-only. A scope narrows; it never widens. The set available to a department is bounded
by the organization's, and a project's by its department's — organization ⊇ department ⊇ project.
A grant that exceeds the level above is refused with
403. - Server-enforced. The screen shows the scope controls only to an organization administrator, and
PUT /settings/departments/{id}/scopesrefuses anyone else with"Only a super admin, org admin, or the department owner can grant department scopes."
An empty scope list means "everything the level above allows", not "nothing".
Projects
Settings → Projects (/settings/projects). A project is created with a name; a duplicate is refused
with "A project with that name already exists". From the same screen you can rename a project,
make it your active one, and delete it.
Who may create a project. Organization administrators and department administrators. A project
administrator may not — they administer the project they were given rather than spawning new ones —
and neither may a plain member. The screen reflects this by telling a member with no projects to ask
an administrator rather than offering a button the server would refuse, and POST /project enforces
the same rule with 403.
A department administrator creates inside a department they administer: the request must name
that department (the screen's department selector, or the active department scope), and naming
another one is refused with 403 "You can only create projects in departments you administer."
Organization administrators are unrestricted.
Each project has a mode. auto in the API, shown as Simple in the application; manual in
the API, shown as Advanced. The mode changes how much of the platform a project's members see and
how the ontology is edited, so it is worth setting deliberately
rather than leaving at the default — see project mode. Reading a
project's mode across a scope boundary returns 403, and changing it is restricted to an
administrator and recorded in the audit trail.
How the structure shows up elsewhere
The tree you build here is not only an organizing device; three other things read it directly.
- Roles.
dept_adminandproject_adminare meaningless without the department or project they are scoped to. An invitation carrying one of those roles must carry its scope, and is refused otherwise. See roles and permissions. - Credentials. An API key is minted against one project and can be listed or revoked only by an administrator of that project. See credential management.
- Quota. The per-project ceiling is per project, and the organization ceiling is shared by all of them. Splitting one team into four projects gives each a separate project bucket but does not give them more organization headroom. See quota and credits.