Organizations

An organization is one of your business customers, such as Globex. Its staff sign in through Globex's own identity provider, Microsoft Entra ID, Okta or any SAML or OpenID Connect provider, chosen by the domain of their email address. An organization has its email domains, at most one enterprise connection, and its members. Your app can tell Globex's users apart by the org_id in their tokens, as with Auth0 Organizations.

Adding an organization

Open Admin UI → Tenants → (select tenant) → Organizations and click Add organization. Give it:

• a name, such as Globex
• optionally your own external ID for the customer, unique in the tenant, so you can find the organization without storing Authalla's ID
• its email domains, such as globex.com

An email domain belongs to at most one organization in a tenant. Set only domains you know the customer owns: Authalla trusts them as given, and once the organization's connection is on, its users can sign in only through it.

Then set up its connection yourself (see SSO connections), or send the customer's IT admin a setup link and let them do it.

Its connection

An organization's enterprise connection is one of:

• Draft: new, and not yet proven. It signs no one in and its domains don't route to it. A passing test sign-in turns it on.
• Enabled: its domains route to it, and their users can sign in only through it.
• Disabled: turned off. Its domains don't route to it, and their users sign in the way they did before.

The Organizations tab lists each organization's connection with its status and its last test sign-in. It flags:

• a Draft, so you know whose setup to chase;
• Certificate expires in N days, when a SAML connection's identity provider certificate expires within 30 days, and Certificate expired after. The identity provider will sign with a new certificate, which the connection needs before then: ask the customer's IT admin to update it, through a setup link or on the connection's page. The change waits for a test sign-in before it goes live.

Single sign-on is required once the connection is on

Once an organization's connection is enabled, users with an email at its domains can sign in only through it. A PIN code, magic link, passkey, social login or sign-up for such an email is refused, and the user is sent to the connection instead. That covers a magic link or code sent before the connection was turned on, and a social account or passkey the user set up earlier. Each refusal is a Failed sign-in with the reason Sent to single sign-on.

While the connection is a draft or turned off, these users keep signing in the way they did, so a customer can move to single sign-on without a gap. Turning the connection on doesn't sign anyone out: sessions and refresh tokens already issued run out on their own.

This can't be turned off for a domain. A user who must keep another way to sign in needs an email outside the organization's domains.

A connection also only signs in emails at its organization's domains. If the identity provider returns an email at any other domain, the sign-in is refused, so one customer's identity provider can't sign in as a user of another.

Sending users to an organization

If your app already knows which organization a user belongs to, for example from a subdomain or a customer picker, add organization with the organization's ID to the authorize request:

https://{tenant-id}.authalla.com/oauth2/authorize?client_id=…&organization=org_8h2kd93hf0s

The user skips the email step and goes straight to the organization's identity provider. If the organization has no enabled connection, or isn't one of the tenant's, the sign-in ends on an error page. A user already signed in some other way signs in again through the organization's connection.

Tokens from a sign-in through an organization's connection carry its ID as org_id, in the ID token and the access token, whether the user got there by organization or by their email domain. No scope is needed, and refreshed tokens keep it. A user who signed in any other way has no org_id.

An organization's members

A user becomes a member of an organization when they sign in through its connection. A test sign-in makes no one a member. On the organization's page, Members lists them, the most recent single sign-on first, and shows when each last signed in that way. You can also:

• See who isn't on single sign-on yet: active users with an email at the organization's domains who have never signed in through its connection, and how each still signs in (a magic link, a PIN code, a passkey or another connection). They become members on their first sign-in through the connection.
• Add a member by email, even a contractor with an email on another domain. If the tenant has no user with that email yet, one is created, so you can add someone before their first sign-in. Give a name, or their identity provider fills it in when they sign in. Once the organization's connection is enabled, you can also email them that they can now sign in with their organization's account. The email comes from the tenant's sender address in its branding and default language, and its Sign in button goes to the tenant's default app.
• Remove a member, optionally signing them out everywhere too. The user stays in the tenant, and signing in through the connection makes them a member again, so to offboard someone, remove their access in the identity provider first.
• Sign out every member: Sign out everywhere for each member at once. They can sign in again unless you remove their access in the identity provider first.

Users in the organization's header opens the users list showing only its members. On the users list, pick a tenant and then an organization to do the same. Once any user belongs to an organization, the list has an Organization column, and each user's page names their organizations in its header.

A user can be a member of several organizations.

Through the Management API and MCP

Everything on the organization's page is also in the Management API, under /management/v1/tenants/{tenant_id}/organizations, and in the MCP server:

• organizations and their email domains, with organizations:read and organizations:write
• members, read with organizations:read and changed with organization-members:write
• the setup link, with portal-links:write, so your backend can send a signed-in admin of your customer straight into setup
• the connection, at …/organizations/{organization_id}/connection, with its test sign-in and pending changes, read with organizations:read and changed with organizations:write. It works as in the setup portal, and you can also turn a draft on without a test sign-in, and delete a connection that has been on.

See Account API keys for the scopes.

Deleting an organization

Deleting an organization deletes its connection, email domains, members and setup links. Its users stay in the tenant. With the connection gone, their domains no longer require single sign-on, so they sign in with the tenant's other sign-in methods, if it has any.