Guests

Organizations rarely work alone. A partner's engineers join a launch project, an agency's designers need the brand folder, an auditor reads the books for a quarter. Making them ordinary members leaves accounts behind long after the work ends, nobody remembers who asked for them, and their own company was never asked.

Better IAM lets an organization invite them as guests, by email, and keeps three things true for every guest:

• Someone vouches for them. Every guest has a sponsor, an active member of the host organization who is not a guest themselves. The sponsor renews the guest's access, or lets it end.
• Access ends. A guest's access lasts a limited time (90 days by default). Everything the invitation granted ends with it unless the sponsor renews it.
• Both organizations agree. The host's inbound settings decide who may join as a guest. When the invited address is on a domain another organization has verified, that organization's outbound settings must allow it too.

A guest is an ordinary person (kind: 'user') of the host tenant that carries a server-owned marker, Identity.guest (sponsorId, since, homeDomain, and homeTenantId for people from another organization). It is never an attribute and never a separate kind of identity, so everything the host already uses applies to guests unchanged: roles and bindings, groups, access packages, separation of duties, access invariants, certifications, identity expiry, and offboarding. Policies see principal.guest, principal.guestSponsorId, and principal.homeTenantId, and a tenant can set a guest boundary that caps everything its guests do.

Everything lives in the guests API group (client.guests.* over HTTP), plus two scheduled jobs on iam.guests.

Setup

Guests are always on: the guests API group and iam.guests exist on every instance. They need email delivery, because every invitation is an email.

import { betterIam } from 'better-iam';
import { sqliteAdapter } from 'better-iam/adapter-sqlite';
import { renderDeliveryMessage } from 'better-iam/auth/templates';
import { mailer } from './mailer';

export const iam = betterIam({
  database: sqliteAdapter({ filename: './iam.db' }),
  secret: process.env.BETTER_IAM_SECRET!,
  baseURL: process.env.BETTER_IAM_BASE_URL!,
  authentication: {
    sendEmail: async (message) => {
      const rendered = renderDeliveryMessage(message, {
        appName: 'Acme Cloud',
        links: {
          guestInvitation: ({ tenantId, token }) =>
            `https://app.acme.test/join?tenant=${tenantId}&token=${encodeURIComponent(token)}`,
          guests: ({ tenantId, guestId }) =>
            `https://app.acme.test/${tenantId}/guests${guestId ? `/${guestId}` : ''}`,
        },
      });
      if (rendered) await mailer.send({ to: message.to, ...rendered });
    },
  },
});

npx better-iam migrate --config better-iam.config.mjs

import { createIamClient } from 'better-iam/client';
import type { iam } from './iam';

export const client = createIamClient<typeof iam>({ baseURL: 'https://app.acme.test' });

Usage

Invite a guest

const invitation = await iam.api.guests.invite(admin, {
  tenantId,
  email: 'gina@partner.example',
  sponsorId: alice.id, // defaults to the caller, who must then be able to sponsor guests
  message: 'Welcome to the launch project',
  roleIds: [viewerRoleId],
  groupIds: [launchGroupId],
  packageIds: [partnerKitId],
  accessDays: 30, // how long access lasts after redemption: 1 to 365, default the tenant's (90)
  expiresInDays: 7, // how long the invitation can be redeemed: 1 to 30, default 14
});

Route: POST /api/iam/guests/invite

invite needs iam:guests:invite and an email delivery callback (authentication.sendEmail; DELIVERY_REQUIRED otherwise). It emails a personal guest-invitation with a token (biam_gst_…, a prefix secret scanners can look for), stores only the token's hash, and returns the invitation without it. It is refused when:

• someone in the organization already has the address, or it already has a pending invitation (CONFLICT; send the pending one again or revoke it);
• the address is on one of the organization's own verified domains (GUEST_NOT_ALLOWED): that person is a member, so invite them as one;
• the cross-tenant access settings of either organization do not admit the person (GUEST_NOT_ALLOWED);
• the caller is impersonating someone (IMPERSONATION_RESTRICTED), the organization is not active (TENANT_INACTIVE), or it is the platform tenant (INVALID_INPUT);
• the caller acts through an assumed role (ACCESS_DENIED): redemption re-checks the inviter's own rights, which a role session does not carry, so such an invitation could never be redeemed.

Domains are compared in their canonical form: lowercase, an internationalized domain in its punycode form, and without a trailing dot (gil@globex.example. is gil@globex.example). The invitation stores and emails that form, and an address whose domain is not a DNS name is refused (INVALID_INPUT).

Choose the sponsor

The sponsor is the caller unless sponsorId names someone else. A sponsor must be an active, unexpired person of the organization who is not a guest (INVALID_SPONSOR otherwise). Callers who cannot sponsor, such as a root administrator, a service account's API key, or a delegated session, name a sponsor explicitly. Naming someone else also needs iam:guests:manage (ACCESS_DENIED otherwise, whoever the named person is), as giving a guest another sponsor does: the sponsor answers for the guest, and policies may grant on principal.guestSponsorId.

What an invitation may grant

Roles, groups, and packages are authorized when the invitation is sent, exactly as identities.invite and packages.assign authorize them:

• iam:bindings:create on each role, never a protected role;
• iam:groups:update on each group, never a team's backing group (TEAM_MANAGED), with the authorities behind the group's own bindings;
• iam:packages:assign on each package, with the rights to assign it by hand.

Roles and groups also need a grant authority (GRANT_AUTHORITY_REQUIRED). An invitation therefore never grants more than its inviter could grant directly, and redemption checks this again. A group that holds a license product, named directly or included in a package, also needs iam:licenses:assign.

Link the email to your page

renderDeliveryMessage renders the email. Give it a links.guestInvitation builder that points at your own page (without one, the email shows the token), and a links.guests builder for the review and missing-sponsor emails (without one, they fall back to links.account):

import { renderDeliveryMessage } from 'better-iam/auth/templates';

sendEmail: async (message) => {
  const rendered = renderDeliveryMessage(message, {
    appName: 'Acme Cloud',
    links: {
      guestInvitation: ({ tenantId, token }) =>
        `https://app.acme.test/join?tenant=${tenantId}&token=${encodeURIComponent(token)}`,
      guests: ({ tenantId, guestId }) =>
        `https://app.acme.test/${tenantId}/guests${guestId ? `/${guestId}` : ''}`,
    },
  });
  if (rendered) await mailer.send({ to: message.to, ...rendered });
},

Redeem an invitation

The invitee opens your page and chooses a name and a password. guests.redeem is public (the emailed token is the credential), takes no credential argument on the server, and works from the browser client:

import { client } from './lib/iam-client';

const result = await client.guests.redeem({ tenantId, token, name: 'Gina', password });
if ('mfaRequired' in result) {
  // The tenant requires MFA: the new guest enrolls a factor before a session is issued.
}

Route: POST /api/iam/guests/redeem

Redemption happens in one transaction, so a refusal leaves the invitation usable:

Over HTTP, POST /api/iam/guests/redeem sets the session cookie like the other invitation routes, and on an organization's own sign-in address it acts in that organization only. Redemption is rate limited per organization (500 attempts), per client address (20, when the request carries a client IP), and per token (10), each within the rate-limit window (authentication.rateLimits.windowMs, 15 minutes by default), so tokens cannot be guessed. The client's own budget is counted first, so one client cannot use up the organization's budget that every invitee shares. It is audited as guest:redeem with the new guest as the actor.

The guest then signs in like any member (auth.signIn with their email and password), and the tenant's authentication policy applies to them. Their email address cannot change: identities.update and the guest's own auth.requestEmailChange refuse it (INVALID_INPUT), because the invitation proved that address and the cross-tenant settings admitted it. Invite the new address instead.

Manage invitations

const [oldest] = (await iam.api.guests.listInvitations(admin, { tenantId, status: 'pending' })).reverse();
if (oldest) await iam.api.guests.resendInvitation(admin, { tenantId, invitationId: oldest.id, expiresInDays: 7 });

Route: POST /api/iam/guests/listInvitations (also /guests/revokeInvitation, /guests/resendInvitation)

• listInvitations({ tenantId, status? }) lists invitations newest first, never with tokens. A pending invitation past its lapse is reported as expired before the sweep job records it.
• revokeInvitation({ tenantId, invitationId }) withdraws a pending invitation (iam:guests:manage).
• resendInvitation({ tenantId, invitationId, expiresInDays? }) sends a pending or lapsed invitation again with a new token (the old one stops working) and a new lifetime (iam:guests:invite). The address, the cross-tenant settings, the sponsor (INVALID_SPONSOR), and the original inviter's rights (INVITATION_INVALID) are checked again first, so only an invitation that can still be redeemed goes out.

When the inviter or the sponsor is disabled, offboarded, deleted, or contained by threat detection, their pending guest invitations are revoked (revokedReason: 'inviter-inactive' or 'sponsor-inactive').

The guest directory

list({ tenantId, sponsorId?, status?, expiringWithinDays?, limit?, offset? }) returns guests by name with a total, and get({ tenantId, identityId }) returns one guest (iam:guests:read). Each guest carries the identity's status, the guest account's accountStatus, the sponsor (sponsorId, sponsorName, and sponsorMissing when the sponsor left), homeTenantId and homeDomain, the invitation and inviter, redeemedAt, the last renewal (attestedAt, attestedBy), the next review (reviewDueAt), the access end (expiresAt), and the last sign-in (lastSignInAt).

expiringWithinDays keeps guests whose access ends at most that many days from now, ended ones included (add status: 'active' to leave them out). Sponsors see the guests they vouch for without any permission: mine({ tenantId }) lists their active guests, the soonest review first, from their own session or API key.

const { guests, total } = await iam.api.guests.list(admin, { tenantId, expiringWithinDays: 14, status: 'active' });
const gina = await iam.api.guests.get(admin, { tenantId, identityId: ginaId });

Route: POST /api/iam/guests/list (also /guests/get, /guests/mine)

Renew a guest's access

A guest's access ends at its expiresAt. Past it, every credential of the guest is refused at once, and the retention worker (iam.purgeDeleted) disables the identity and records identity:expire, as for any identity with a deadline. The sponsor keeps the guest by renewing (attesting) their access:

await iam.api.guests.attest(aliceSession, { tenantId, identityId: ginaId, days: 90 });

Route: POST /api/iam/guests/attest

• The guest's sponsor renews from their own session without any permission, never while impersonating. Anyone else needs iam:guests:manage on iam/guests/{identityId}. Guests renew nobody's access, their own included.
• The access then ends days from now (1 to 365, default the tenant's accessDays), and the next review is due after the tenant's reviewEveryDays, or at the new end if that comes first.
• What the invitation granted moves with it: its bindings, group memberships, and package assignments get the new end, also when an administrator changed the guest's expiresAt in between. Grants whose end was changed by hand keep theirs, and a package assignment keeps its end when the package's maxDurationMs does not allow the new one. Renewing lengthens only what the invitation granted at redemption, so it needs no iam:licenses:assign for licensed groups.
• A guest who owns the organization keeps an owner's protection: renewing them needs an owner or root caller, as identities.update does for an owner's expiry (their sponsor alone cannot), and never gives the last owner an end.
• A guest whose access ended, or who is disabled, cannot be renewed (INVALID_TRANSITION). An administrator restores them with identities.update (a later expiresAt) and identities.setStatus (active); the next sweep reopens their guest account. A former guest's disabled identity keeps their address, so inviting the address again is refused (CONFLICT) until that identity is deleted.

Change the sponsor

Route: POST /api/iam/guests/setSponsor

setSponsor({ tenantId, identityId, sponsorId }) gives an active guest a new sponsor (iam:guests:manage and a recent sign-in). The change reaches decisions at once through principal.guestSponsorId. Guests never choose a sponsor, their own included, and never make anyone a member (ACCESS_DENIED), whatever roles they hold.

When a sponsor leaves:

• Offboarding with a successorId who can sponsor guests hands the leaver's guests to the successor (each audited as guest:sponsor-change); without one they are flagged sponsorMissing. identity:offboard reports guestsReassigned and guestsUnsponsored when they are not zero.
• Deleting the sponsor flags their guests sponsorMissing.
• The sweep job flags guests whose sponsor was disabled, expired, or can otherwise no longer sponsor, and emails the organization's owners once per guest and loss (guest-sponsor-missing).

A flagged guest keeps their access until it ends. Assign a new sponsor with setSponsor, or remove the guest. The flag clears when the sponsor can sponsor again.

End a guest's access

await iam.api.guests.remove(admin, { tenantId, identityId: ginaId, reason: 'Launch project finished' });
// Or keep the person for good, as an ordinary member:
await iam.api.guests.convertToMember(admin, { tenantId, identityId: gilId, clearExpiry: true });

Route: POST /api/iam/guests/remove (also /guests/convertToMember)

• Let it lapse. Access ends at expiresAt unless the sponsor renews it.
• Remove the guest. remove({ tenantId, identityId, reason }) (iam:guests:manage, a recent sign-in) disables the identity and, in one transaction, ends its sessions, keys, and delegations, removes every role binding, group and team membership, package assignment, activation, and relationship it holds (whichever authority granted them), cancels its pending requests and invitations, revokes the grant authorities it holds, and closes the guest account as removed. It returns the counts and is audited as guest:remove. The guest's license seats are released right after, so the next person waiting moves up. Expired guests can be removed too; an owner cannot (transfer ownership first).
• Offboard or delete. identities.offboard closes a guest's account as removed (reason "Offboarded"), and deleting the identity removes its guest account. The audit trail keeps the history.
• Make them a member. convertToMember({ tenantId, identityId, clearExpiry? }) (iam:guests:manage, a recent sign-in) removes the guest marker, closes the guest account as converted, and re-runs the birthright rules, which now treat the person as a member. Decisions see the change at once, in the person's current session too. The access end stays unless clearExpiry: true removes it together with the end of what the invitation granted; for a guest who owns the organization, only an owner or root caller clears it. Keeping someone in a licensed group for good claims its seats, so clearExpiry also needs iam:licenses:assign when a license product is assigned to one of those groups (ACCESS_DENIED, audited as a denial).

Cross-tenant access settings

Each tenant has cross-tenant access settings. They are open until configured:

await iam.api.guests.configure(admin, {
  tenantId,
  inbound: {
    allowGuests: true,
    allowedDomains: ['partner.example', 'agency.example'],
    blockedDomains: ['competitor.example'],
    partners: [{ tenantId: globexTenantId, allow: true }],
  },
  outbound: {
    allowGuestInvitations: false,
    partners: [{ tenantId: initechTenantId, allow: true }],
  },
  accessDays: 30,
  reviewEveryDays: 14,
});

Route: POST /api/iam/guests/configure (also /guests/getSettings)

configure needs iam:guests:settings and a recent sign-in. Only the fields given change, inside inbound and outbound too, and an unknown field is refused (INVALID_INPUT), so a misspelled setting cannot leave the tenant unguarded. Domains are host names such as partner.example, stored lowercase, deduplicated, and sorted. Partner lists name existing tenants other than this one, each at most once (100 per list). The boundary is validated like any policy (INVALID_POLICY, INVALID_ACTION). getSettings returns the current settings, with configured: false while the tenant uses the defaults.

Who decides admission

An address whose domain another tenant has verified belongs to that tenant: the guest is tenant-sourced, guest.homeTenantId names that tenant, and both sides decide. Addresses at domains nobody verified need only the host's inbound settings. Admission is decided in this order:

1. The host refuses a person whose organization it lists as a partner with allow: false.
2. The host refuses an address at a blocked domain.
3. The host admits a person whose organization it lists as a partner with allow: true.
4. Otherwise the host needs allowGuests, and an address at an allowed domain when allowedDomains is set.
5. The home organization must allow it: its outbound partner entry for the host when it has one, else allowGuestInvitations.

A refusal is GUEST_NOT_ALLOWED (403). The home organization's refusal only says that the person's organization does not allow it, never what it configured. Admission is checked when an invitation is sent, sent again, and redeemed.

Options

Guests have no server option of their own; each tenant's cross-tenant access settings hold its guest policy. These deployment settings change how the module behaves:

Per invitation, accessDays (1 to 365) overrides the tenant's access length and expiresInDays (1 to 30, default 14) sets how long the invitation can be redeemed.

Policies for guests

The keys describe a person in their own tenant, in their own session, API key, session token, or a delegated session in which an agent acts for them. An assumed role never carries them (principal.guest is false). The server owns them: values supplied by resolveContext or a plugin are removed, and identity attributes cannot use the names guest, guestSponsorId, or homeTenantId. Access analysis (policies.simulate, whoCan, effectiveActions) evaluates a guest as the guest they are, and policies.test defaults principal.guest to false unless its context passes it.

{
  "version": 1,
  "statements": [
    {
      "sid": "GuestsNeverAdminister",
      "effect": "deny",
      "actions": ["iam:*"],
      "resources": ["*"],
      "conditions": { "Bool": { "principal.guest": true } }
    },
    {
      "sid": "NoGuestsInPayroll",
      "effect": "deny",
      "actions": ["payroll:*"],
      "resources": ["*"],
      "conditions": { "Bool": { "principal.guest": true } }
    },
    {
      "sid": "GuestsUseMfa",
      "effect": "deny",
      "actions": ["documents:*", "projects:*"],
      "resources": ["*"],
      "conditions": { "Bool": { "principal.guest": true, "principal.mfa": false } }
    },
    {
      "sid": "GuestsReadTheirSponsorsDocuments",
      "effect": "allow",
      "actions": ["documents:read"],
      "resources": ["document/*"],
      "conditions": {
        "Bool": { "principal.guest": true },
        "StringEquals": { "resource.ownerId": "${principal.guestSponsorId}" }
      }
    },
    {
      "sid": "GlobexInJointProjects",
      "effect": "allow",
      "actions": ["projects:read", "projects:comment"],
      "resources": ["project/joint-*"],
      "conditions": { "StringEquals": { "principal.homeTenantId": "<Globex tenant ID>" } }
    }
  ]
}

• principal.guest is always present, so a deny statement on it needs no guard.
• A variable whose key is absent never matches, so members get nothing from GuestsReadTheirSponsorsDocuments.
• principal.guestSponsorId and principal.homeTenantId are absent for members and for guests without a home tenant, and a missing key never satisfies a negated operator. To refuse every guest who is not one of Globex's people, deny both the guests from elsewhere and the guests without a home tenant (policy lint's optional-key-deny warns about the first statement alone):

[
  {
    "effect": "deny",
    "actions": ["projects:*"],
    "resources": ["project/globex-*"],
    "conditions": {
      "Bool": { "principal.guest": true },
      "StringNotEquals": { "principal.homeTenantId": "<Globex tenant ID>" }
    }
  },
  {
    "effect": "deny",
    "actions": ["projects:*"],
    "resources": ["project/globex-*"],
    "conditions": {
      "Bool": { "principal.guest": true },
      "Exists": { "principal.homeTenantId": false }
    }
  }
]

The guest boundary

A tenant's guestBoundary is a ceiling on every guest's decisions there, like a tenant or principal boundary: it never grants anything, and a guest can do only what both their grants and the boundary allow. It bounds agents acting for a guest too, including the scopes of the delegation tokens they are issued. Members are not bounded by it, and it stops applying the moment a guest becomes a member. Use it as a safety net that holds whatever roles a guest is given by mistake:

await iam.api.guests.configure(admin, {
  tenantId,
  guestBoundary: {
    version: 1,
    statements: [
      {
        effect: 'allow',
        actions: ['documents:read', 'documents:comment'],
        resources: ['document/shared-*'],
      },
    ],
  },
});

Birthright rules and guests

Automatic assignment rules gain the key identity.guest (a boolean, tested with Bool or Exists). A rule that never tests it does not match guests: rules written for members, such as { StringEquals: { 'principal.kind': 'user' } }, never reach people from outside the organization. The same applies to onboarding flow rules and lifecycle workflow scopes, which use the same language.

// A kit for every guest
{ include: [{ StringEquals: { 'principal.kind': 'user' }, Bool: { 'identity.guest': true } }] }

// Everyone, guests included: Exists always holds, and testing the key lets guests match
{ include: [{ StringEquals: { 'principal.kind': 'user' }, Exists: { 'identity.guest': true } }] }

// Guests from one partner domain (redemption verifies the address)
{
  include: [
    {
      StringEquals: { 'principal.kind': 'user' },
      Bool: { 'identity.guest': true, 'identity.emailVerified': true },
      StringEqualsIgnoreCase: { 'identity.emailDomain': 'partner.example' },
    },
  ],
}

// Members only, stated explicitly
{ include: [{ StringEquals: { 'principal.kind': 'user' } }], exclude: [{ Bool: { 'identity.guest': true } }] }

Testing identity.guest anywhere in a rule lets guests match all of it, so a rule that tests it in one include clause also lets guests match its other include clauses. packages.previewAutoAssign warns about each such clause. Rules apply to a guest right after redemption, and again after convertToMember.

Schedule the jobs

Two jobs on the instance keep guests tidy. Run both hourly, followed by an outbox run:

setInterval(async () => {
  await iam.guests.sweep();
  await iam.guests.sendReviewReminders();
  await iam.auth.dispatchOutbox();
}, 60 * 60_000).unref();

• iam.guests.sweep({ tenantId? }) marks lapsed invitations expired, closes the guest accounts of guests whose access ended (guest:expire) and reopens those an administrator restored, removes the accounts of deleted identities, flags guests whose sponsor can no longer sponsor and emails the owners (guest-sponsor-missing, once per guest and loss, when the deployment sends email and the tenant is active), and drops partner entries naming organizations that were purged. It returns invitationsExpired, accountsExpired, accountsRestored, sponsorsMissing, ownersNotified, and partnersRemoved.
• iam.guests.sendReviewReminders({ tenantId?, withinDays? }) emails each sponsor (guest-review) about guests whose review is due or whose access ends within withinDays (default 14, 1 to 90). Each review date and each access end is reminded once, and one email covers whatever is due for a guest, so an unanswered review reminder never stands in for the warning that access is about to end. It needs an email delivery callback (DELIVERY_REQUIRED), skips inactive tenants and sponsors without an address, and returns { sent, skipped: { inactive, quiet } }.

Both run each tenant in its own transaction and are safe to repeat. The retention sweep (iam.sweepExpired()) deletes redeemed, revoked, and expired invitations 90 days after they lapsed; the audit trail keeps every invitation. Guest invitations, guest accounts, and cross-tenant access settings (collections guestInvitations, guestAccounts, and crossTenantAccess) are purged with their tenant. See Scheduled jobs for the other jobs a deployment runs.

Permissions

setSponsor, remove, convertToMember, and configure also need a recent sign-in. Enforced access invariants guard iam:guests:manage and iam:guests:settings calls and every redemption, since each can change what someone may do.

Events and emails

Every call made with a permission records its operation event (iam:guests:*). The module also records these, subscribable as guest:* with a webhook. Changes made through the API are recorded by the person who made them, guest:redeem by the new guest, and the jobs by deployment-operator. No event carries an invitation token.

renderDeliveryMessage renders the three emails. Times in their payloads are ISO-8601 strings.

In the console

Directory → Guests lists an organization's guests with their sponsor, access end, next review, and last sign-in, invites new ones, and shows sponsors the guests they vouch for so they can renew them. A guest's page renews access, changes the sponsor, makes the guest a member, or removes them. Guest invitations can be sent again or revoked, and Directory → Cross-tenant access edits the settings. Member pages mark guests with a Guest badge and their sponsor. Invitees accept at /cloud/join?kind=guest, and the console runs both jobs hourly.

Limits

Not in this version

• Signing in with the home organization. A tenant-sourced guest has an account of its own in the host tenant and signs in there with the password they chose at redemption. Signing in to the host with a session of the home tenant is planned.
• Passwordless redemption. Redemption sets a password; passkeys and other factors can be added afterwards.
• SCIM. Guests are not mapped to SCIM's userType: "Guest", and inbound SCIM provisioning creates members, not guests.

Schema

A guest is an ordinary identity with the server-owned Identity.guest marker; the module adds three tenant-scoped collections in the shared iam_records table, purged with their tenant.

Errors

Next steps