Skip to content

Organizations (B2B)

An organization is a customer company inside a realm: its verified email domains route its people to its own identity provider, its own staff administer it in a console limited to it, its people carry organization roles in their tokens, and its own SCIM client can provision it.

What it is

One realm hosts many customer organizations. They share the realm's clients, keys and sign-in pages, but each organization has:

  • members, each with organization roles and, optionally, one manager;
  • units (department, team, group) in one tree per organization;
  • verified domains that decide who belongs to it at sign-in;
  • its own identity providers, usable only for its verified domains;
  • invitations, policies, a SCIM token and branding.

A user can be a member of several organizations. Sign-in settles on one active organization, and tokens carry it (see Organizations in tokens).

Note

Organizations and groups are complementary. An organization says which customer a person belongs to; roles and groups say what a person can do in the realm. Organization roles only grant rights inside the organization, and only through the org:* permissions below.

Concepts

Members and organization roles

A member is a realm user inside the organization. A member holds organization roles (replacing the old free-text role). Each role carries a set of org:* permissions:

Permission Lets the holder
org:view read the organization, its members, roles, units, org chart, settings, policy and branding
org:members add and remove members, set roles and managers
org:invitations invite people by email, resend, revoke
org:domains add, verify and remove domains
org:sso manage the organization's identity providers
org:units create, move and delete units, set unit members and unit roles
org:roles create, change and delete organization roles
org:policies change the organization's settings and policy
org:scim create and revoke the organization's SCIM tokens
org:branding change sign-in branding and theme

Every organization has a built-in role, Org admin, with all ten permissions; it cannot be changed or deleted. The last member holding it cannot lose it or be removed (409). A role may have at most 10 permissions.

Rules that stop escalation (see Organization admin guide): an organization admin can only grant permissions they hold themselves, and can only take away from a role, or delete, permissions they hold.

Units and the org chart

Units are one tree per organization: department, team or group, nested up to 8 levels, at most 1000 units per organization (409 with code unit-limit beyond that). A unit can grant roles; members of the unit and of its descendants inherit them. A member can also have one manager (another member of the same organization, no cycles). The org chart is the manager tree.

Domains

An organization claims a domain by publishing a DNS TXT record and verifying it:

  1. Add the domain. HelixIAM returns a challenge: a name _helixiam-challenge.<domain> and a value helixiam-verify=<token>.
  2. Publish that TXT record at your DNS provider.
  3. Verify. HelixIAM looks the record up (5 second timeout; 10 attempts per organization per 10 minutes, counted per server pod). When the record is not found yet, the verify call answers 400 with code dns-record-not-found and the domain stays pending; publish or correct the record and verify again.

A domain is verified by at most one organization per realm (409 code taken for the second). Verified domains are re-checked daily; after three checks in a row that get an answer without the record, the domain goes back to pending and stops routing sign-in and auto-join (audit event ORGANIZATION_DOMAIN_UNVERIFIED, metric helix_org_domain_unverified_total). A lookup that fails (timeout, resolver error) does not count; it is logged and counted in helix_org_domain_recheck_errors_total.

Refused as a claim: IP addresses, single-label names, public suffixes (400 code public-suffix; this includes a name directly under a reserved suffix such as acme.example, so the examples here use acme-bv.example.com), the built-in public email providers (for example gmail.com, outlook.com, hotmail.com, yahoo.com, icloud.com, proton.me) and any domain on the realm's blocked domains list (see Realm settings). Nothing routes on a pending domain.

Sign-in

The active organization is settled in this order: the organization parameter on the authorization request; else the user's email domain, in an identifier-first step (shown only when the realm has at least one verified domain, and it never reveals whether an account exists); else, when the user is a member of more than one organization, an organization picker (unless every candidate has the picker switched off). One membership means that organization.

With a discovered organization that has an enabled identity provider, the user is sent to it. More than one enabled provider shows a choice of those only.

The identifier step checks the entry inline (EN and NL) and never starts discovery for an empty or malformed address. A username (no @) goes on to the password step. Where the realm has usernames, the field is labelled "Email address or username" ("E-mailadres of gebruikersnaam"): a text field that opens the email keyboard. A realm that signs in by email address keeps "Email address".

With ssoOnly on, the refusal comes before the password is checked, so a right and a wrong password get the same answer. An address in a verified domain of such an organization gets that same answer whether or not an account has it. A directory (LDAP/AD) sign-in decides it before the user bind: on the typed address's domain, or for a typed username on the mail address the directory search returned. A bind therefore never confirms the password of a first-time directory user of that organization.

On the organization's own sign-in pages the panel shows the organization's logo and, when its theme sets no tagline, the line "Sign in with your {organization} account".

Organization settings

Setting Effect
autoJoin (off) A user with a verified email in a verified domain becomes a member at first sign-in or registration
ssoOnly (off) Password, passkey and OTP first-factor sign-in is refused for users in a verified domain of the organization and for its active members; realm and master admins are exempt. Needs at least one enabled non-LDAP identity provider of the organization (409 otherwise)
allowPicker (on) Whether the organization appears in the picker
invitationTtlDays (7) How long an invitation stays valid, 1 to 30 days
requireMembership (organization field, off) Only members may complete a sign-in where this organization is the active one

requireMembership applies whenever the active organization was determined, by parameter, domain or picker. Identity providers of the realm itself are not covered by ssoOnly; it limits the local factors.

When a non-member is refused, a browser first gets a not-a-member page (EN and NL, HTTP 403, in the realm's look; it names no organization). It offers Back to the application, which returns access_denied with the request's state to the client, and Sign in with another account. The page is sent with X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin and the sign-in pages' Content-Security-Policy. Switching its language does not audit the denial a second time. prompt=none and non-browser requests get the access_denied answer at once, without the page.

Organization identity providers

An organization admin creates OIDC or SAML identity providers owned by the organization (other protocols are refused with 400). An assertion from such a provider is accepted only when the asserted email is in a verified domain of that same organization; otherwise it is refused (audit ORGANIZATION_IDP_DOMAIN_REFUSED). Users created on first sign-in through it become members (provisionedBy: jit:<providerId>). Secrets are write-only.

Invitations

Invite an email address with organization roles (only roles the inviter may grant). Invitations are sent by email, so the realm needs an email provider (see Notifications); without one, inviting answers 409 with code email-not-configured. The emailed link is single use and expires after the organization's TTL; HelixIAM stores only a hash of the token. At most 200 invitations may be pending per organization. The invited person signs in, or registers (also when the realm's self-registration is off, for that email only). The account's verified email must equal the invited email, so a forwarded link is useless to someone else. Resending replaces the link; revoking ends it.

  • Registering from the link. The emailed link proves the invited address: a new account registered from it is created verified (no second confirmation email), joins at once and sees "You joined {organization}" in the organization's branding. If the invitation was revoked or expired in the meantime, the page says the account was created but not added to the organization.
  • An existing account that has not verified the invited address verifies it first ("Verify your email address first"); that page offers to send the realm's verification email. An address the person set in the account console stays unverified until they verify it, so a forwarded link never verifies it for them.
  • Invite-time strength. The permissions of each invited role are recorded when the invitation is sent or resent. If a role gained permissions since, it is granted on accept only while the member who approved it (the inviter, or whoever resent the invitation last) still holds the added permissions; otherwise it is left out (accept audit detail rolesWidened).
  • Rate limits (cluster-wide): 5 sends an hour per invited address (sends and resends together), 100 per inviter and 300 per organization. Past a limit: 429 with code invitation-rate-limited and Retry-After, audited as ORGANIZATION_INVITATION_RATE_LIMITED. Settings: helix.organizations.invitations.rate-limit.per-address-per-hour, .per-inviter-per-hour, .per-org-per-hour.
  • The email. Subject "Invitation to join {organization}" (NL "Uitnodiging voor {organization}"); the body names the inviter by full name (else username), says the link is personal and must not be forwarded, and uses the organization's branding. Its footer reads "Sent by {organization} via {realm}." (NL "Verstuurd door {organization} via {realm}.") unless the theme sets its own footer text; this applies to every email sent in an organization's context. A customized invitation template keeps its own subject. The invitation pages are branded as the inviting organization, tab title included.

Policies

An organization can require MFA (and limit which methods count to totp, webauthn and push, the methods a step-up page can ask for; push only where the realm offers the Authenticator app. A list of only sms or email is refused with 400, and the method list needs MFA required), a longer minimum password, a longer password history and shorter idle and maximum session times (60 seconds to one year). Each field may only be stricter than the realm's; weaker is a 400 naming the realm's value. The active organization's MFA and session policy apply at sign-in; the organization password fields (passwordMinLength, passwordHistory) apply, as the strictest across all of the user's organizations and the realm, when an existing member changes or resets their password. A new account is checked against the realm's rules when it is created (registration, admin and SCIM creation), because it has no membership yet.

SCIM

Each organization can have its own SCIM tokens. They work on the same /realms/{realm}/scim/v2 endpoints as the realm token (with the same per-token rate limit), and limit every operation to that organization: Users are its members, Groups are its units, the enterprise department attribute maps to a department unit and manager to the manager link. SCIM cannot deactivate or remove a member who holds an organization permission (for example an Org admin); an organization admin or a realm admin removes them. See SCIM.

Branding

Display name, logo (https) and primary colour for the organization's sign-in pages, plus a full theme layer. See Login theming. The hosts of an organization's identity-provider logos are allowed in the page CSP (img-src) only on pages branded as that organization, not on every page of the realm.

Watch: Create an organization and set it up

57 seconds, no sound. Create an organization, add a member with the Org admin role, create an organization role and look at the Domains and Policies tabs. Recorded on the current release.

In the console

Realm admins: Manage → Organizations. Click New organization, set the name and display name, then click Create organization. Open the organization: it has the tabs Overview, Members, Invitations, Structure, Roles, Domains, SSO, Policies, SCIM, Branding. Appoint the first organization admins by giving a member the Org admin role. The organization's own staff then use the Organization admin guide.

The console is English only.

Over the API

Examples assume $HELIX_URL, $REALM and an admin session with the CSRF header, as in Authenticating to the API; write calls add -H "X-XSRF-TOKEN: $CSRF". Placeholders such as $ORG and $ROLE are ids returned by earlier calls.

# create an organization (realm admin)
curl -s -b cookies.txt -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d '{"name":"acme-bv","displayName":"Acme BV","enabled":true,"requireMembership":false}' \
  "$HELIX_URL/admin/realms/$REALM/organizations"

# add a domain, then read the challenge and verify
curl -s -b cookies.txt -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d '{"domain":"acme-bv.example.com"}' \
  "$HELIX_URL/admin/realms/$REALM/organizations/$ORG/domains"
curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/organizations/$ORG/domains"
curl -s -b cookies.txt -X POST -H "X-XSRF-TOKEN: $CSRF" \
  "$HELIX_URL/admin/realms/$REALM/organizations/$ORG/domains/$DOMAIN/verify"
[
  {
    "id": "…",
    "domain": "acme-bv.example.com",
    "status": "pending",
    "challengeName": "_helixiam-challenge.acme-bv.example.com",
    "challengeValue": "helixiam-verify=…",
    "verifiedAt": null,
    "lastCheckedAt": null,
    "failedChecks": 0
  }
]
# an organization role with two permissions
curl -s -b cookies.txt -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d '{"name":"HR","description":"People team","permissions":["org:view","org:members"]}' \
  "$HELIX_URL/admin/realms/$REALM/organizations/$ORG/roles"

# make an existing realm user a member with that role (replaces the member's roles)
curl -s -b cookies.txt -X PUT -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d "{\"roleIds\":[\"$ROLE\"]}" \
  "$HELIX_URL/admin/realms/$REALM/organizations/$ORG/members/$USER"

# invite someone by email
curl -s -b cookies.txt -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d "{\"email\":\"anna@acme-bv.example.com\",\"roleIds\":[\"$ROLE\"]}" \
  "$HELIX_URL/admin/realms/$REALM/organizations/$ORG/invitations"

# a department, and the org chart
curl -s -b cookies.txt -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d '{"name":"Finance","type":"department"}' \
  "$HELIX_URL/admin/realms/$REALM/organizations/$ORG/units"
curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/organizations/$ORG/org-chart"

An organization reads as {"realmId","orgId","name","displayName","enabled","requireMembership","memberCount","createdAt","verifiedDomains",…}: createdAt is epoch milliseconds and verifiedDomains lists the organization's verified domains (read-only; a realm import never trusts it, imported domains start pending).

The org chart is {"roots":[{"userId","username","displayName","email","provisionedBy","reports":[…]}]}. Members and org-chart nodes carry displayName: given name and family name, else the name attribute, else null. A member without a name has username: null; a client shows its own fallback (full name, then username, then email), never the id.

Member email addresses

Holders of org:view see member email addresses on these admin routes only (the member list and the org chart). Invitations are by email, so an organization admin needs them. On the organization admin routes only holders of org:view see them; tokens never carry them. (SCIM Users responses and the realm user admin API return email addresses to their own callers, the SCIM token holder and realm admins.)

Full endpoint set

All under /admin/realms/{realm}. A realm or master admin may call all of them; an organization admin may call the ones under /organizations/{orgId} with the permission shown (the one table OrganizationRoutePermissions decides, and an unlisted route is realm-admin only).

Method & path Purpose Permission for an organization admin
GET /organizations List (an organization admin sees only their own organizations) —
POST /organizations Create realm admin only
GET /organizations/{orgId} Read org:view
PUT · DELETE /organizations/{orgId} Update / delete realm admin only
GET /organizations/{orgId}/members List members. roleIds and roleNames are the direct grants; inheritedRoles lists the roles held through a unit, each as {roleId, roleName, unitId, unitName} with the unit that grants it (the member's unit or an ancestor) org:view
PUT · DELETE /organizations/{orgId}/members/{userId} Change roles of a member, or add one / remove a member. Adding an existing realm user by id is for realm admins only: an organization admin gets 404 for a user who is not yet a member org:members
PUT /organizations/{orgId}/members/{userId}/manager Set or clear a manager: body {"managerUserId":"<userId>"}, or {"managerUserId":null} to clear it. The manager must be a member of the same organization (404 otherwise); oneself or a cycle is 400. Any other field name is ignored, so the manager is cleared org:members
GET /organizations/{orgId}/roles · GET .../roles/{roleId} List / read roles org:view
POST /organizations/{orgId}/roles · PUT · DELETE .../roles/{roleId} Create / change / delete a role org:roles
GET · POST /organizations/{orgId}/domains List (with challenge) / add org:domains
POST /organizations/{orgId}/domains/{domainId}/verify · DELETE /organizations/{orgId}/domains/{domainId} Verify / remove org:domains
GET · POST /organizations/{orgId}/identity-providers List / create an organization provider org:sso
GET · PUT · DELETE .../identity-providers/{alias} Read / update / delete org:sso
GET · POST /organizations/{orgId}/invitations List / invite org:invitations
POST /organizations/{orgId}/invitations/{invitationId}/resend · DELETE /organizations/{orgId}/invitations/{invitationId} Resend / revoke org:invitations
GET /organizations/{orgId}/units · GET .../units/{unitId} · GET .../units/{unitId}/members Read units org:view
POST /organizations/{orgId}/units · PUT · DELETE .../units/{unitId} Create / update or move / delete a unit org:units
PUT · DELETE /organizations/{orgId}/units/{unitId}/members/{userId} Add / remove a unit member org:units
PUT /organizations/{orgId}/units/{unitId}/roles Set the roles a unit grants org:units
GET /organizations/{orgId}/org-chart Manager tree org:view
GET · PUT /organizations/{orgId}/settings autoJoin, ssoOnly, allowPicker, invitationTtlDays read org:view, change org:policies
GET · PUT /organizations/{orgId}/policy MFA, password, session policy read org:view, change org:policies
GET · POST /organizations/{orgId}/scim-tokens · DELETE .../scim-tokens/{tokenId} List / create (shown once) / revoke org:scim
GET · PUT /organizations/{orgId}/branding Sign-in branding (display name, logo, colour) read org:view, change org:branding
GET · PUT /organizations/{orgId}/theme Sign-in theme layer read org:view, change org:branding
GET /me/scope What the caller administers: kind (master, realm, organization or none), organizations (each orgId, name, displayName, permissions), and who the caller is: userId, displayName (full name, else username; never an id) and realmDisplayName any signed-in user

See the API reference for every field.

See also