Team & roles

Invite teammates, assign roles, resend invitations, and how WorkOS/Authio SSO fits the sign-in flow.

Organization admins manage hiring teammates from Settings → Team (/dashboard/settings/team). The page lists active members, pending invitations, last login, and role badges.

Who can manage the team

Only users with Organization Admin permissions (canManageOrganization) see the Team tab and can invite, edit, or remove members. Recruiters and hiring managers can view their own Account settings but cannot change org membership.

Inviting a teammate

1. Open Settings → Team.
2. Click Invite team member.
3. Enter email, first name, last name, and role.
4. Submit — InsightHire creates the user row, sends an invitation email, and marks invitationStatus = PENDING.

The invite email uses InsightHire's branded template (not a generic provider sender). The accept link routes through Authio SSO (WorkOS-backed identity) so the invitee creates credentials or signs in with your company's SSO if configured.

Resending invitations

For members who never completed signup, use Resend invitation on their row. Resend is available when:

• invitationStatus === PENDING, or
• The user has never logged in (legacy invites before status tracking)

Resending is idempotent — it reuses the existing invitation token rather than creating duplicate Authio/WorkOS invites.

Available roles

The team settings UI exposes two primary roles (legacy role strings are normalized for display):

Legacy values (ADMIN, ORG_ADMINISTRATOR, RECRUITER) map to Organization Admin in the UI. Fine-grained recruiter vs hiring-manager distinctions for pipeline actions are enforced at the position and API layer — see Roles & permissions.

Changing roles

Admins can edit an existing member's role from the member row menu. Role changes take effect immediately on the next API call; they do not revoke in-progress sessions until token refresh.

Removing members

Removing a member deactivates their org access. Historical audit activity (scorecards, messages, approvals) retains their user ID for attribution. You cannot remove the last Organization Admin without promoting another member first.

SSO and Authio

InsightHire recruiter authentication runs through Authio (identity layer backed by WorkOS User Management). Relevant fields on the org and user records:

• organizations.workosOrganizationId / authioOrganizationId — links your tenant to the identity provider
• users.workosId — links each recruiter to their Authio/WorkOS user
• users.authProvider — AUTHIO_SSO for standard recruiter sign-in

Enterprise SSO

When your company configures SSO (SAML/OIDC) in Authio/WorkOS:

1. Users with matching email domains sign in through your IdP.
2. Team invites still create the InsightHire user row first; the invitee completes signup via SSO on first login.
3. lastLoginAt is updated from Authio on each successful callback.

SSO is configured at the platform/Authio level, not inside InsightHire settings. Contact InsightHire support or your CSM to connect your IdP.

Passkeys

Individual users can add passkeys from Settings → Account (passkeys-settings component). Passkeys supplement SSO — they do not replace org-wide SSO policy.

Invitations list (secondary surface)

Settings navigation also links to /dashboard/team/invitations for a dedicated pending-invite view. Functionally equivalent to the Team page invite list; use whichever fits your workflow.

Approval chains and role-based approvers

When job governance is enabled, approval chain steps can target:

• Specific users (approverType: USERS), or
• Everyone holding a role (approverType: ROLE) — e.g. all Organization Admins

Role slugs in approval settings mirror org roles: ORGANIZATION_ADMIN, RECRUITER, HIRING_MANAGER, etc. See Job governance.

Security notes

• Invitation emails contain single-use accept URLs; expired invites require resend.
• Platform admins can impersonate org users from InsightHire Admin for support — this bypasses normal SSO and is audit-logged.
• Removing a user does not delete their Authio account; it only revokes org membership in InsightHire.

Troubleshooting