Organizations

Serve your business customers from one realm: each organization has its own members, proven domains, sign-in providers and branding, and is named in the tokens.

An organization is one of your customers — a company that buys your product — living inside a realm. Its people are ordinary users of the realm; the organization says whose people they are, which providers they sign in through, which branding they see and, through org_id in the token, which customer a request belongs to.

You do not need a realm per customer. One realm, one set of clients, and an organization for each company you serve.

What an organization holds

Part	What it does
Handle	The alias your application sends to ask for this customer’s sign-in, such as `globex`. 2 to 64 lowercase letters, digits and hyphens, starting and ending with a letter or digit; unique in the realm and fixed once created.
Members	The users of the realm who belong to it. Membership says whose people they are and grants nothing on its own.
Domains	Email domains the customer proved it controls, by DNS.
Sign-in providers	External identity providers of the realm offered to this customer, such as their own Microsoft Entra directory.
Branding	Logo, primary colour and background colour, applied over the client’s sign-in screen. Anything left empty keeps the client’s.
Status	A suspended organization admits nobody, is ignored at sign-in and is no longer named in tokens. Its members, domains and providers are kept.

Organizations have no invitations and no roles of their own. Add members from the console or let a proven domain admit them, and give permissions with roles, directly or through groups.

Set up an organization

Create it
Open Organizations, choose New organization, pick the realm and give it a display name and a handle. The handle is suggested from the name; check it now, because it cannot change later.
2
Prove a domain
On the organization’s Sign-in tab, choose Claim a domain and type it, such as globex.com. Publish the TXT record shown on that domain, then choose Verify:
DNS TXT record on globex.comPlain text
authio-domain-verification=<value shown in the console>
The domain moves from Awaiting proof to Proven. Verification is not retried on its own: publish the record first, then verify. A domain can belong to only one organization.
Offer its sign-in providers
Still on Sign-in, choose Offer a provider and pick among the identity providers registered in the realm. See Social and enterprise sign-in to register one.
Add members
On the People tab, choose Add member and pick users of the realm — or let a proven domain admit them, as below.
Brand it
In the organization’s edit screen, set the logo URL and the colours its people see at sign-in.

Automatic membership by domain

Turn on Admit arrivals automatically and anyone who finishes signing in with a confirmed address at one of the organization’s proven domains becomes a member, with no invitation.

Two proofs are required: the domain verified by DNS and the person’s address confirmed — by Authio, or asserted as verified by a trusted external provider. A local sign-up on an unconfirmed someone@globex.com does not get in.
The switch is set after the organization exists and does nothing until a domain is proven.
When the application names an organization at sign-in, only that one can admit the person.
A failure to admit never fails the sign-in: the person signs in without the organization.

Add organization, with the handle, to the authorization request. Your application decides which customer is signing in — usually from the subdomain or a path segment it was opened on — and passes it through.

Authorization requestPlain text

https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/auth
  ?client_id=acme-web
  &response_type=code
  &redirect_uri=https%3A%2F%2Fapp.acme.com%2Fapi%2Fauth%2Fcallback%2Fauthio
  &scope=openid%20profile%20email
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=af0ifjsldkj
  &organization=globex

With a handle, the hosted login draws the organization’s branding and offers the providers offered to the organization in place of the client’s. A handle that names no active organization is ignored, and the sign-in goes on as an ordinary one.

Naming an organization does not restrict who signs in

A person who is not a member signs in normally and receives tokens without org_id. Check org_id or org_alias in your application before serving a customer’s data.

Organizations in tokens

When a sign-in belongs to an organization, both the access token and the ID token name it:

Access token payloadJSON

{
  "iss": "https://authio.api.hyperio.tech/realms/acme",
  "sub": "6f1c2e7a-4b8d-4f0e-9a51-3c2d7e8b9f10",
  "azp": "acme-web",
  "scope": "openid profile email",
  "org_id": "b3e1d7c4-2f6a-4e9b-8d1c-7a5f0e2b4c96",
  "org_alias": "globex",
  "exp": 1791372600
}

Authio decides the organization when the sign-in completes, in this order:

If the request named an organization, that one — provided the person is a member, or was just admitted by domain, and the organization is active. Otherwise the token names none.
If the request named none, the organization the person was just admitted to by a proven domain.
Otherwise, the person’s organization when they belong to exactly one active organization.
Otherwise, none: org_id and org_alias are left out.

Use org_id as the key for the customer in your own data. Token introspection returns both claims as well.

Suspend or delete

Suspending keeps the organization whole — members, domains, providers — and stops it from admitting anyone, shaping the sign-in or being named in new tokens.
Deleting removes its domains, the providers offered to it and every membership. The users stay in the realm.

Each organization can also decide which external accounts its people may connect on its behalf; see Connected accounts.

Next steps

Social and enterprise sign-inRegister the identity providers you offer to each customer.Roles and permissionsDecide what each person may do once they are in.Hosted loginThe screens your customers’ people sign in on.Connected accountsGovern which external accounts are used for each organization.