# Organization admin guide

This guide is for the people who administer **one customer organization** (for example the IT or HR staff of Acme BV). You sign in to the same console as the realm's operators, but you see, and can change, only your own organization.

## Watch: Sign in as an organization admin

<figure class="hx-video" markdown="0">
  <video controls preload="none" playsinline width="1920" height="1080" poster="/assets/videos/organization-admin.jpg" aria-label="Screen recording: what an organization admin sees and does in the admin console">
    <source src="/assets/videos/organization-admin.mp4" type="video/mp4">
  </video>
  <figcaption>43 seconds, no sound. Sign in as an organization admin, add a domain, open the invitation form and look at Roles and SCIM. Recorded on the current release.</figcaption>
</figure>

## Signing in

Your realm admin gave you the *Org admin* role (or another organization role with `org:*` permissions) in your organization. Open the console of your realm and sign in with your normal account. The console asks the server what you administer (`GET /admin/realms/{realm}/me/scope`) and shows an **Organization** console limited to your organization; if you administer several, you can switch between them. The console is English only.

!!! note "Reachability"
    If the operator restricts the console to certain hosts (for example a VPN-only console), you reach it on a host they added for customers. See [Console reachability for customer organization admins](../getting-started/install.md#console-reachability-for-customer-organization-admins).

You can only act inside your own organization and your own realm. Nothing you do reaches another organization, realm-level clients, roles, identity providers or settings.

## Tabs and permissions

Each tab appears only when you hold its permission. The server checks the permission on every request, whatever the console shows.

| Tab | Permission to see and change it | What you do there |
| --- | --- | --- |
| Overview | `org:view` | The organization's name, status and settings (changing settings needs `org:policies`) |
| Members | `org:members` (read-only with `org:view`) | Change members' roles and managers, remove members |
| Invitations | `org:invitations` | Invite by email, resend, revoke |
| Structure | `org:units` | Unit tree (department, team, group) and the org chart |
| Roles | `org:roles` | Organization roles and their permissions |
| Domains | `org:domains` | Claim and verify email domains |
| SSO | `org:sso` | The organization's own identity providers (OIDC or SAML) |
| Policies | `org:policies` | MFA, password and session rules, auto-join, single sign-on only |
| SCIM | `org:scim` | Tokens for your own provisioning client |
| Branding | `org:branding` | Sign-in name, logo, colour and theme |

!!! info "Who sees email addresses"
    Holders of `org:view` see member email addresses in the member list and the org chart. Among the organization admin routes, only holders of `org:view` see them; tokens never carry them. The console needs them because invitations and domain rules work on email addresses. Members and the org chart show a member's full name, else their username, else their email address, never an id; a member with none of these appears as "Unnamed user". The member list is in name order.

## Day-to-day tasks

### Claim and verify a domain

1. **Domains → Add domain**, enter `acme-bv.example.com`.
2. Copy the record shown: name `_helixiam-challenge.acme-bv.example.com`, type TXT, value `helixiam-verify=<token>`.
3. Publish it at your DNS provider, wait for DNS to update, then click **Verify**.

Public email providers (such as gmail.com) and public suffixes cannot be claimed, and neither can any domain the realm operator blocked. A domain another organization of this realm has verified answers "taken" (409). Verified domains are re-checked daily; if the record is gone for three checks in a row the domain returns to *pending* and stops routing your people to your identity provider and stops auto-join. Keep the TXT record in place.

```bash
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/acme/organizations/$ORG/domains"
curl -s -b cookies.txt -X POST -H "X-XSRF-TOKEN: $CSRF" \
  "$HELIX_URL/admin/realms/acme/organizations/$ORG/domains/$DOMAIN/verify"
```

### Connect your identity provider

**SSO → Add provider**: choose OIDC or SAML (the console offers only those two) and enter the settings from your IdP. Secrets are write-only; leave a secret blank when editing to keep it. The provider works only for your verified domains: an assertion for an email outside them is refused. After you add and enable it, people with a verified-domain email are sent to it at sign-in. Users who sign in through it for the first time become members. The provider's **Trust email** and **Trust AMR** settings are set by a realm administrator: a change to them from you is refused (403), and saving the provider without them keeps their current values.

With **Single sign-on only** on (Policies tab), password, passkey and one-time-code sign-in is refused for your domain's users and your members. This needs at least one enabled OIDC or SAML provider of yours; the server refuses the setting otherwise, and refuses to remove the last such provider while it is on. Realm administrators are exempt so the operator cannot be locked out; you are not exempt. The refusal comes before the password is checked and is the same for an address no account has, so it tells nobody whether a colleague has an account.

### Invite people

**Invitations → Invite**: enter the email and choose roles. You can only offer roles whose permissions you hold yourself. The person gets a single-use link, valid for the number of days in your settings (1 to 30, default 7). They sign in or register with **that same email address**: an account with another verified address cannot accept, and the email tells them the link is personal. Someone who registers from the link has their address verified by it and joins at once; an existing account whose address is not verified yet verifies it first (the page offers the verification email). At most 200 invitations may be pending; **Resend** replaces the link, **Revoke** ends it. Invitations go out by email: until the realm operator sets up an email provider, inviting fails with "This realm cannot send email yet" (409 `email-not-configured`).

Sending is limited to 5 invitations an hour to one address (sends and resends together), 100 an hour per inviter and 300 an hour per organization; past that the console says to try again later (429 `invitation-rate-limited`). A role you invite someone with is granted at the strength it had when you sent or resent the invitation: if it gained permissions since, it is granted only while you (or whoever resent it last) still hold them.

### Roles, members and units

- Create a role with only the permissions it needs. **Org admin** is built in and cannot be changed or deleted.
- A member's roles can come from direct grants and from the units they are in (a unit grants its roles to its members and to the members of its sub-units).
- Set a manager for a member from **Members**; the **Structure** tab shows the org chart.
- Your own row in **Members** offers no **Remove**: leaving is not an administrator action on yourself.
- Up to 8 levels of units and 1000 units per organization.

### Provision with SCIM

**SCIM → Create token**: the token is shown once. Configure your provisioning client with base URL `https://<host>/realms/<realm>/scim/v2` and `Authorization: Bearer <token>`. See [SCIM](../integration/scim.md#per-organization-tokens). SCIM cannot deactivate or remove a member who holds an organization permission (for example an *Org admin*), take them out of a unit that grants one, or delete such a unit. An organization admin or a realm admin removes them in the console.

### Policies

You can require MFA for your members, limit which methods count, raise the minimum password length and history, and shorten the idle and maximum session times. Each value must be at least as strict as the realm's; the console shows the realm's value, and the server refuses a weaker one (400). Your MFA and session policy applies to sign-ins where your organization is the active one.

## What you cannot do (by design)

- **Grant what you do not hold.** Giving a member a role, or putting permissions in a role or a unit, is refused (403) unless you hold every permission involved.
- **Take away what you do not hold.** Removing permissions from a role, deleting a role, or removing a role from a member, is refused (403) when it would take away permissions you lack. This stops a smaller admin from pushing a stronger one out.
- **Remove the last Org admin.** The last member holding the *Org admin* role cannot lose it or be removed (409).
- **Add arbitrary realm users.** People join your organization by invitation, SCIM, a verified domain (auto-join) or your identity provider. Adding an existing realm user directly by id is for realm administrators only.
- **See or change realm-level objects.** Realm roles, clients, realm identity providers and realm settings are not reachable.

Every change you make is written to the audit log with the realm, your organization and you as actor.

## Over the API

The console uses the same API, so everything above is scriptable with the same permissions: see the [endpoint table](organizations.md#full-endpoint-set).

## See also

- [Organizations (B2B)](organizations.md)
- [Organizations in tokens (client guide)](../integration/organizations-client.md)
- [Admin roles (RBAC)](../operations/admin-roles.md)
