Organizations, departments and projects

An organization is a customer, the outermost boundary. Below it are departments and projects. You need an organization administrator for most steps; a department administrator can create projects in their department.

Sign up at /signup and type your organization's name (enter the signup key you were given, if asked). The organization is created and you own it.
On the first-run screen (/onboarding), create a first department and a first project, or skip either.
Open Settings, then Organization (/settings/org), to set the name and primary domain.
Open Settings, then Departments (/settings/departments), and create a department with a name.
Open Settings, then Projects (/settings/projects), and create a project with a name inside a department.

Limits

Limit	Behavior
Signup key	Required by default; a deployment setting.
Create a department	Org Admin or owner only. Duplicate name: `409`.
Delete a department	Refused with `409` while it has members.
Create a project	Organization or department administrators. Duplicate name is refused.
Scopes	Restrict-only. An empty scope list means everything the level above allows.

More details

Getting started as an administrator

The path an administrator takes runs from having no account to having a working project.

You need a browser and, on a default deployment, a signup key from whoever operates it. Nobody has to create your organization first: it is made for you when you sign up, and you become its owner.

How it works as a first run

You sign up at /signup, typing your organization's name into the form.
Wexa creates the organization, names it from what you typed, and records you as its owner. You are signed in at once.
A first-run screen at /onboarding asks for a first department and a first project. Each step can be skipped.
Wexa fills any gap a skip left, so a project exists before you reach the main application.
Everything after that lives under Settings in the main application.

Open /signup.
Enter your first and last name, your email address, a password (twice), and your organization's name.
If the page asks for an invite key, enter the key you were given. Whether it asks depends on the deployment.
Submit. The account is created already active and the response carries login tokens, so you are signed in immediately. Email verification is deliberately skipped.

Whether the key is demanded is a deployment decision, not a per-account one. The signup page checks GET /users/signup-config, which returns { accessKeyRequired }, before it renders the form. That value is backed by the SIGNUP_ACCESS_KEY_REQUIRED setting, which defaults to required.

On a default deployment you cannot create the first account for your company unaided, so ask whoever operates the deployment for a key.

Signup is one database transaction, so two concurrent signups cannot spend the same key twice.

Know which key you were given

Key kind	Use	Lifetime	What redeeming it does
Platform scope	Minted for one email address	Single-use, expires after a day	Creates a new organization
Organization scope, already bound	Reusable	Never expires	Joins that organization, and only if the email has also been invited
Organization scope, not yet bound	Reusable	Never expires	The first redemption creates an organization and binds the key to it permanently, so every later redemption joins rather than creates

For the invitation side, see members and invitations.

Finish the first-run screen

There is no separate "create an organization" step, and no screen that offers one. The organization section below covers what that means for the rest of the set-up.

A new account lands on /onboarding, which renders outside the main shell, with no navigation and no project switcher, until it is finished. It has two steps, in order:

Create your first department. Skippable.
Create your first project. Skippable.

Skipping is not the same as doing nothing:

What you do	What you get
Skip the department, create the project	The project you named, with no department
Create the department, skip the project	A project called `Default` inside it
Skip both	A department called `General`, renameable later, with a `Default` project inside it

A project must exist before the gate lifts, so the second step always resolves to a project one way or another.

Whatever you create yourself is kept, because the automatic provisioning only fills the gaps a skip left behind. The screen does not reappear on a later sign-in: the check is server-side and asks whether you own a project, not whether you clicked through the screen once.

Find the administration screens

After the first run, open Settings in the main application. Organization is /settings/org (name, primary domain, deployment posture and the organization's reusable join key), Departments /settings/departments and Projects /settings/projects, covered on this page. Users (/settings/users) and Roles (/settings/roles) are covered in Members and roles. Developer access (/settings/developer-access) issues, lists and revokes API keys; see Credential management.

Set up before anyone else arrives

Once a project exists, the set-up worth doing first is short:

Decide your structure. Departments group projects and people, and a project is the unit of isolation. Getting this wrong is expensive to undo, so read the sections below before you create the second one.
Decide who administers what. Wexa distinguishes an organization-wide administrator from one scoped to a department or a single project. See roles and permissions.
Invite people with their role and scope set in the invitation, not afterwards. The invitation carries the role and the department or project, and the access it implies is materialized the moment they accept.
Issue credentials last, and only for the projects that need programmatic access. A key can do nothing the person who minted it could not already do.

How it works

The organization is created at signup, by the first account in it. No screen or administrator endpoint creates one.
A department is the unit of delegated administration. It owns no work of its own; it owns who administers what, and carries an allow-list of what its projects may reach.
A project is the unit of isolation. Its context graph, knowledge base, data catalog, ontology, agents and their executions belong to exactly one project and are not visible from another.
Scopes narrow downwards. Organization contains department contains project, and a grant can only restrict.

Decide what to create

If two teams must not see each other's material, they need two projects; nothing weaker will do it. A department administrator administers every project beneath it without being named on each one, so a department pays off only when several projects share one administrator.

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, such as a trial before a rollout	Two projects	The trial's context and ontology should not survive into the rollout
A team that needs different 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

Avoid 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 hardest shape to collapse later.

Create your organization

You do not create an organization from inside an existing one. The name typed into the organization name field on the signup form becomes the organization, the person signing up is recorded as its owner, and it all happens in the same transaction that creates the account. With no name supplied it is called Default Organization.

Whoever signs up first owns the organization. If that should be a particular person, they should be the one to sign up.
A second organization means a second signup, redeeming a key that is not yet bound to an organization.
One person can belong to several organizations. GET /users/org-list returns the set and the organization switcher reads it, but each membership came from a separate signup or invitation.

Configure the organization

Settings, then Organization (/settings/org), reads and writes through GET and PUT /settings/organizations/{id}.

Section	Field	Editable?
Org profile	Organization name	Yes, by an organization administrator
Org profile	Primary domain	Yes, by an organization administrator
Org profile	Tenant ID	No, shown for reference
Identity provider	Single sign-on and directory provisioning status	Displayed only
Deployment posture	Cloud, on-premises or air-gapped	Displayed; contact your account team to change it

The update endpoint accepts name, primaryDomain, deploymentMode (cloud, on_prem or air_gapped), and status objects for the identity provider and directory provisioning. The screen gates the first two behind an organization administrator and the posture behind the platform administrator.

GET /settings/organizations/{id}/health backs an environment-health section. It currently returns an empty component list and a timestamp, and the screen hides the section. An empty panel is not a fault.

Use the join key

Every organization has one reusable, non-expiring access key, which lets a colleague sign up into your organization.

GET /settings/organizations/{id}/access-key returns it, creating one lazily for an organization that predates the feature. Anyone but an organization administrator gets 403 "Only a super admin or org admin can view the org access key."
POST /settings/organizations/{id}/access-key/invite with an email records that address on the allow-list and emails a signup link with the key filled in.

The key alone admits nobody. Signup needs the key and an allow-list entry for that exact email, and otherwise refuses with "This access key is registered to an org which this email hasn't been invited to", so a leaked key is not a way in. Do not hand the raw key out; use the invitation flow in members and roles.

Manage departments

Settings, then Departments (/settings/departments). The same operations are served by identity at /departments and /settings/departments.

Create. The screen asks for a name only. A duplicate is refused with 409 "A department with that name already exists." Only an Org Admin or the organization's owner may create one; anyone below gets 403 "Only a super admin or org admin can create a department." from both POST /departments and POST /settings/departments, and the "New department" button is hidden for them.
Rename. Safe: people and projects stay attached.
Delete. Refused with 409 "Cannot delete a department with N member(s)." while it has people, so move them first.
Change. PUT and DELETE are reserved for organization-wide administrators, the department's own owner and its own administrators. A department administrator scoped elsewhere gets 403 "You can only manage departments you administer.", enforced on the server as well as hidden in the screen.

Set department scopes

Open a department (/settings/departments/{id}) to set which projects it reaches, which modules, connectors, models, entity types and actions its work may use, and a clearance for sensitive data classes.

Restrict-only. A scope narrows and never widens. A department is bounded by the organization and a project by its department, and a grant above the level above is refused with 403.
Server-enforced. The screen shows the controls to an organization administrator only, and PUT /settings/departments/{id}/scopes refuses 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.

Manage projects

Settings, then Projects (/settings/projects). Create a project 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. Organization administrators and department administrators. A project administrator or plain member may not, and POST /project refuses them with 403. A member with no projects is told to ask an administrator instead of being offered a button.
Where a department administrator creates. Inside a department they administer: the request must name it, through the screen's department selector or the active department scope. Naming another gets 403 "You can only create projects in departments you administer." Organization administrators are unrestricted.
Mode. Each project is Simple (auto in the API) or Advanced (manual). Set it deliberately; see project mode. Reading a project's mode across a scope boundary returns 403, and changing it is restricted to administrators and recorded in the audit trail.

Limits and behavior

Topic	Behavior
Platform-scope key	One email address, single use, expires after a day.
Organization-scope key	Reusable, never expires.
Email verification	Skipped. The new account is active and signed in.
Onboarding screen	Shown until you own a project, then never again.
Concurrent signups	One transaction, so a key cannot be spent twice.

More limits

Topic	Behavior
Request quotas	Shipped defaults are 120 requests per project and 600 per organization per sliding 60-second window, `0` meaning unlimited. Teams in one organization can exhaust each other's headroom.
Per-project buckets	Splitting a team into four projects gives four project buckets but no more organization headroom.
Roles	`dept_admin` and `project_admin` need their department or project, and an invitation carrying one without it is refused.
Credentials	An API key is minted against one project and listed or revoked only by an administrator of that project; see credential management.
Audit	Lifecycle and audit records carry the organization on every entry; see lifecycle and audit.

Members and roles: invite people and decide what each role reaches.
Project mode: choose and switch between Simple and Advanced.
Usage, quota and billing: how the request ceilings are counted against your organization.
Core ideas: the concepts behind the structure.
Policy and approvals and lifecycle and audit: the governance behind project mode.