Invitations

Members join a Thalix Vault organization only through explicit administrator-sent invitations. A new sign-in must match either the configured bootstrap identity (the first administrator) or an active identity_invitations row in the database. This page explains how administrators invite members, what happens when they click the link, how invitations expire and revoke, and how to reactivate an invited member who was deactivated. For definitions of invitations, deactivation, audit event, and correlation ID, see Glossary.

Invite a new member

An administrator sends an invitation to an email address:

tv admin user invite person@example.com

By default, the invitee receives the user role and the invitation expires in 7 days:

Invitation sent to person@example.com.
Role: user
Expires: 2026-09-02T15:38:49.123Z
Correlation ID: 3b617b19-…

To invite with a different role or expiry:

tv admin user invite person@example.com --role admin --expires-days 14

Accepted values:

• --role <admin|user> (default: user)
• --expires-days <n> (default: 7 days; any positive integer)

On success, a confirmation email is sent to the invitee's address containing a clickable link. Behind the scenes, tv admin user invite is idempotent: if an unconsumed invitation already exists for that email, resending creates a new email but reuses the same database row, updating its role and expiry while preserving the invitation's creation time in the audit log.

If the email is already an active organization member, the invite is refused with ALREADY_MEMBER and no email is sent.

Errors

• ALREADY_MEMBER: the email is already an active member; no invitation is created.
• INVITATION_EMAIL_INVALID: the supplied email address is malformed.
• INVITATION_EXPIRY_INVALID: the --expires-days value is invalid (must be a positive integer).
• FORBIDDEN: the caller is not an admin or global_admin.

Accept an invitation

The invitee receives an email with a subject line like "Invitation to join Thalix Vault" and a clickable link in the body. Following that link:

1. The browser opens https://vault.thalixinc.ai/api/internal/auth/callback with an authentication token in the URL fragment (never sent to any server).
2. A client-side JavaScript shim reads the token, validates it, and establishes a session.
3. If valid, the invitee is signed in and immediately becomes an active member of the organization with the role specified when the invitation was sent.
4. The invitee is then prompted to set a password or reset a forgotten one before day-to-day sign-in.

Important: Invitation links are one-time-use. After accepting, the same link does not work again. If the invitee closes the browser or loses the link before clicking it, an administrator must resend the invitation with tv admin user invite <email>.

List pending and consumed invitations

View all invitations—pending, accepted, revoked, and expired:

tv admin user invites

Email               Status     Role  Expires
person@example.com  pending    user  2026-09-02T15:38:49Z
other@example.com   accepted   admin 2026-08-28T12:00:00Z
retired@example.com revoked    user  2026-09-10T00:00:00Z
3 Invitation(s)
Correlation ID: 9f131577-…

Each invitation shows:

• Email: the recipient's email address.
• Status: pending (not yet clicked), accepted (invitation link was clicked and membership claimed), revoked (administrator revoked it), or expired (current time is past the expiry).
• Role: the role granted when the invitation is accepted or was accepted.
• Expires: the UTC time the invitation is no longer valid.

Errors

• FORBIDDEN: the caller is not an admin or global_admin.

Revoke a pending invitation

If you sent an invitation by mistake or the invitee will no longer join, revoke it:

tv admin user uninvite person@example.com

Invitation to person@example.com revoked.
Correlation ID: 3b617b19-…

Revoked invitations remain in the audit log forever but cannot be accepted, even if the invitee still has the link from the original email. A revoked member cannot regain access through an old link; you must send a new tv admin user invite to grant fresh access.

Revoking an invitation that is already consumed (was accepted and the member joined) is refused with INVITATION_ALREADY_REVOKED — the member is now in the organization directly and must be deactivated through tv admin user deactivate instead (see Users, roles, and groups).

Errors

• INVITATION_ALREADY_REVOKED: the invitation was already revoked, or is a consumed/expired invitation that cannot be revoked.
• FORBIDDEN: the caller is not an admin or global_admin.

Expired invitations

Invitations automatically expire at the time specified when they were sent (default: 7 days). An expired invitation cannot be accepted, even if the invitee still has the link. To grant access again, send a fresh tv admin user invite.

Deactivate and reactivate members

See Users, roles, and groups for deactivating a member. To reactivate a deactivated member:

tv admin user reactivate person@example.com

User person@example.com reactivated.
Status: active
Correlation ID: 3b617b19-…

Reactivation restores the member's ability to sign in. It does not restore any previous sessions or authentication tokens (those were deleted when the user was deactivated); the member must sign in again with their password.

Errors

• NOT_FOUND: the email is not an organization member.
• FORBIDDEN: the caller is not an admin or global_admin.

Audit

Every invitation action — creation, resend, revocation — is recorded in the audit log. Administrators can retrieve the full history with tv admin audit list --action identity.invitation:

tv admin audit list --action identity.invitation --json

The log shows the administrator who sent the invitation, the timestamp, the invitee's email, whether it was a send or a resend, any revocation, and a correlation ID for support. See Audit and administration for the full audit retrieval reference.

Invitation state machine

An invitation follows this lifecycle:

[pending] ──[click link]──> [accepted] ──(cannot change)
    ↓
[revoked] ──(cannot change)
    ↓
[expired] ──(cannot change)

• pending: An invitation that has not yet been clicked. Can transition to accepted (invitee clicks the link) or revoked (administrator revokes it). Can be resent (reuses the same row, refreshes expiry).
• accepted: Invitation was clicked and the member joined. Cannot be revoked or resent.
• revoked: Administrator revoked the pending invitation. Cannot transition back to pending or become accepted. The revocation is permanent and audited.
• expired: The current time is past the invitation's expiry. Cannot be accepted or revoked (already-expired invitations block revoke to avoid confusion).

Troubleshooting

Invitee says "Link invalid" or "Invitation expired"

The link has either:

• Expired (more than 7 days, or the configured --expires-days, have passed since the invitation was sent).
• Been revoked by an administrator.
• Already been used to accept an invitation.

Solution: Send a fresh invitation with tv admin user invite <email>. The invitee can discard the old link.

Invitee cannot find the email

The invitation email may have landed in spam or is taking time to arrive. Resend it:

tv admin user invite person@example.com

This updates the existing invitation's expiry and sends a fresh email.

Invited someone by mistake

Revoke immediately:

tv admin user uninvite person@example.com

The old link is now unusable. If you later decide the person should join, send a new invitation.