Guides

Invite members

Bring people into an organisation by email invite, set their role up front, auto-join trusted domains, and let users self-serve through the org switcher.

An organisation in OrthID is a tenant: a group of users with shared access and their own roles. There are three ways in - an explicit email invite, an automatic join for a verified domain, and self-serve requests through <OrgSwitcher/>. This guide covers all three.

1. Invite by email

Send an invite and assign the member’s role at the same time. The recipient gets an email with a signed link; accepting it adds them to the organisation with exactly the role you chose. If the person does not yet have an OrthID account, the invite flow creates one as they accept.

scripts/invite-member.ts

import { orthid } from "@orthid/sdk";

// Invite a new member with a role.
const invite = await orthid.organizations.inviteMember({
  organizationId: "org_clinic_42",
  email: "dr.okafor@acmehealth.com",
  role: "clinician",        // "admin" | "clinician" | "member"
  // Optional: expire the invite if it is not accepted.
  expiresInHours: 168,
});

console.log(invite.status); // "pending"

If the user already exists in your environment, add them to the organisation directly instead of emailing an invite:

scripts/add-existing-member.ts

import { orthid } from "@orthid/sdk";

await orthid.organizations.addMember({
  organizationId: "org_clinic_42",
  userId: "user_8sQ1",
  role: "admin",
});

2. Roles on invite

The role on an invite is applied the moment it is accepted, so a new member never lands with broader access than intended. Roles map to scopes through RBAC; keep them least-privilege and promote later rather than over-granting on the way in. An admin can change a member’s role at any time.

scripts/update-role.ts

import { orthid } from "@orthid/sdk";

await orthid.organizations.updateMember({
  organizationId: "org_clinic_42",
  userId: "user_8sQ1",
  role: "member",   // demote from admin
});

3. Auto-join by verified domain

For larger tenants, an explicit invite per person is tedious. Turn on domain auto-join so that anyone signing up with a verified email domain is added to the organisation automatically with a default role. The domain must be verified by the organisation first, the same DNS check used for SSO.

scripts/auto-join.ts

import { orthid } from "@orthid/sdk";

await orthid.organizations.setDomainPolicy({
  organizationId: "org_clinic_42",
  domain: "acmehealth.com",   // must be a verified domain
  mode: "auto-join",          // "off" | "request" | "auto-join"
  defaultRole: "member",
});

Choose request mode for review

Set mode: "request" instead of auto-join when an admin should approve each new member. Matching users then appear as pending requests rather than full members.

4. Self-serve with the org switcher

The <OrgSwitcher/> component gives users a self-serve membership flow with no backend code. From it a user can switch between their organisations, accept a pending invite, request to join a domain they belong to, and - with the right role - invite others. Drop it into your app shell:

app/components/app-shell.tsx

import { OrgSwitcher, UserButton } from "@orthid/react";

export function TopBar() {
  return (
    <header className="flex items-center justify-between">
      <OrgSwitcher allowCreate showInvites />
      <UserButton />
    </header>
  );
}

See the <OrgSwitcher/> reference for its full prop list, including how to gate creation and control which actions members see.

Next steps

Enable SSO so enterprise tenants bring their own directory and provision members with SCIM.
RBAC & permissions to design the roles you assign on invite.