Organisation and seats
How first-run setup creates your organisation, how invitations add people, and what the seat each person holds carries.
Your deployment holds one organisationOrganisationTổ chứcYour company's space in the portal. Each deployment runs one organisation, inside your own AWS account.Open in glossary. First-run setup creates it, and every person who can use the portal holds a seat in it. The seat is what the portal reads on every request.
Key rules
- One organisation per deployment. First-run setup creates it, together with the owner’s seat.
- One seat per person. It carries the person’s department, role and whether they are suspended.
- An invitation must match the sign-in address. Accepting writes the seat onto the account the person signed in with.
- No seat, no access. An account with no directory row is refused.
First-run setup
A fresh deployment holds no organisation and nobody who can sign in. The first person to sign up, here Carol, creates it. The admin walkthrough is First-run wizard.
-
Carol registers and signs in
She registers at Keycloak and signs in. Her token names her and no organisation.
-
Setup asks two questions
The name of the organisation she will own, and whether her people sign in here or through a company provider such as Entra ID or Okta.
-
One request creates everything
It creates the organisation and Carol’s seat, records the organisation and the owner role on her account, and registers the provider in Keycloak.
-
One more pass through Keycloak
The browser passes through Keycloak once more so her token names the organisation. Without this, every later call answers 401.
Until a person holds a seat, the portal answers them only on the sign-up surface:
| Session | Reaches |
|---|---|
| Holding no seat | The sign-up surface only: who is signing up, whether an address is free, the create and join routes, and issuing the provisioning credential, which answers only the owner |
| Holding a seat | Refused by the sign-up surface, answered by the list of waiting invitations, and sent back to the portal |
What can go wrong during setup
- The provider cannot be registered. Keycloak and your provider’s issuer are checked while the address is still free, so the request fails with nothing written.
- The organisation lands, then provider registration fails. The organisation stands and is owned. Finish the provider from organisation settings after signing in.
- The page is reloaded. Setup survives a reload and offers no way back once anything is written. The current step comes from the seats in the directory.
The provisioning credential
Creating the organisation also mints an OAuth provisioning credential for SCIM. Its secret is shown once. When setup resumes after a reload, the screen shows the client identifier, says the secret is gone and offers another one. Nothing is re-issued on arrival, because issuing a new secret invalidates the one your provider already holds. Details are in SCIM provisioning → Connector credential.
Invitations
Someone joining the organisation registers, signs in and opens an invitation. Accepting writes the promised seat onto the account they signed in with. So the invitation’s address must equal the sign-in address, and the screen refuses to describe the invitation to any other account.
| Rule | Detail |
|---|---|
| Two ways in | The link, which names a token and records that it was opened; or the landing screen, which lists every invitation waiting for the signed-in address |
| Grant | Decided when the invitation is written: member or administrator, never owner, and one named departmentDepartmentPhòng banThe bucket that pays: it owns a budget, limits and which models its people may use. Everyone belongs to exactly one.Open in glossary |
| Refusal | Distinct from withdrawal; it leaves the address free to be invited again |
| Taken link | Reopening it says so, but only to the address the invitation names. Every other refusal looks the same, so nobody can probe which invitations exist |
| After SCIM | Accepting after SCIM already created the person settles that seat in place. It keeps the external id, the provider-owned fields, the status and the department |
When your provider owns the directory (IDP mode), issuing or resending an invitation is refused, and people arrive over SCIM instead. Withdrawing an open invitation stays possible. See Departments → Directory mode.
The seat
A seat is a directory row keyed by the organisation and the account. Every table that names a person names a seat.
| The seat carries | Meaning |
|---|---|
| Department | The person’s cost bucket: exactly one. See Departments |
| RoleRoleVai tròA bundle of capabilities. Everyone has one built-in role — Org Owner, Org Admin or Org User — and groups can add custom roles on top.Open in glossary | The person’s role in the organisation |
| Suspended | Whether the portal has suspended them |
Three records say who is acting, and in which organisation:
| Holder | Meaning |
|---|---|
| Backend session | The organisation the browser acts in |
| Machine token | Names the organisation and is checked against a seat like any other caller |
| Impersonation record | The administrator behind a session acting as somebody else, and when that ends |
An account whose seat is missing is refused at sign-in. Changes to department, role or suspension apply on the next request, because the seat is re-read every time. See Request authentication.
Impersonated sessions
An administrator with the right capability can act as another user for a limited window through impersonationView as someoneXem dưới tư cách người khácSeeing the portal exactly as another person sees it, to reproduce a problem. It needs its own capability and is recorded in the audit log.Open in glossary; how it starts, ends and is audited is on Access approvals → Impersonation.
Why it works this way
Why the organisation and its provider are one request
The second pass through Keycloak, which puts the organisation into the token, sits between creating the organisation and anything else the browser can do. So the organisation and its provider are created in the same request rather than one after the other.
Under the hood
What the creating request writes
- The organisation row and the owner’s seat in the portal directory.
- The organisation and the owner role on the owner’s Keycloak account, through the Keycloak Admin API.
- The provider registration in Keycloak, through the same API.
- The provisioning credential, with the secret kept only as a digest.
