Invitation Lifecycle and Account Linking

Learn about the complete lifecycle of workspace invitations, from sending to acceptance, and how account linking works in Skycloak.

Invitation Overview

Workspace invitations are the primary method for adding team members to your Skycloak workspace. This document explains the complete invitation lifecycle and clarifies common misconceptions.

Key Principles

Manual Acceptance Required

Important: All invitations must be manually accepted by clicking the invitation link. There is no automatic acceptance of invitations, regardless of authentication method.

• Email/Password users - Must click invitation link to accept
• SSO users - Must also click invitation link to accept
• Existing users - Must click invitation link to join a new workspace
• New users - Must click invitation link, create account, then join

Multi-Workspace Membership via Invitations

Users can belong to multiple workspaces at the same time. Membership is additive:

• Accepting a new invitation adds the workspace to your account; you keep your existing memberships
• Each membership carries its own role, assigned by the invitation
• You switch between workspaces using the workspace switcher; your most recent choice is remembered across logins

Note that only membership is multi-workspace. Self-service workspace creation remains one per user: signup provisions exactly one workspace, and any additional memberships come from invitations. Invitations can assign any role except Owner, since ownership is singular and transfers only via an explicit ownership transfer.

Invitation Lifecycle

1. Invitation Creation

When a workspace admin or owner sends an invitation:

Admin Action → Create Invitation → Email Sent → Status: Pending

The invitation contains:

• Unique secure token
• Recipient email address
• Assigned role (workspace:member, workspace:admin, etc.)
• 24-hour expiration time
• Link to acceptance endpoint

2. Email Delivery

The recipient receives an email with:

• Invitation from workspace name
• Inviter’s name
• Assigned role description
• Secure acceptance link
• Expiration notice

3. User Acceptance Flow

New Users

1. Click invitation link
2. Create Skycloak account
3. Verify email (if not using SSO)
4. Invitation automatically accepted
5. Joined to workspace with assigned role
6. Session updated with workspace and roles

Existing Users

1. Click invitation link
2. Login to existing account
3. Invitation accepted
4. Joined to the new workspace with the assigned role, keeping existing memberships
5. Session updated with the new workspace and roles

SSO Users

1. Click invitation link
2. Redirected to SSO login
3. Authenticate with corporate IdP
4. Invitation accepted
5. Joined to workspace with assigned role
6. Session updated with workspace and roles

4. Post-Acceptance

After successful acceptance:

• User’s Keycloak roles are assigned
• Session is refreshed with new permissions
• User can immediately access workspace resources
• Invitation status changes to “accepted”
• Audit log entry created

Account Linking Behavior

Email-Based Matching

Invitations are linked to users by email address:

• Each invitation is sent to a specific email
• Only users with that email can accept the invitation
• Email must be verified (except for SSO users)

SSO and Invitations

Common misconception: “SSO auto-accepts invitations”

Reality:

• SSO provides authentication, not invitation acceptance
• Users must still manually click the invitation link
• SSO users skip email verification but not invitation acceptance
• The invitation link initiates the acceptance process

Preventing Duplicate Accounts

The system prevents duplicate accounts through:

• Email uniqueness validation
• SSO email claim matching
• Automatic account linking for matching emails

Invitation States

Role Assignment

Initial Role Assignment

When accepting an invitation:

1. Role specified in invitation is assigned in Keycloak
2. User’s session is immediately updated
3. Permissions take effect instantly
4. No logout/login required

Role Updates After Acceptance

If an admin changes a member’s role:

1. Role updated in Keycloak
2. Active sessions updated within 5 minutes
3. User may need to refresh browser for UI updates

Common Scenarios

Scenario 1: SSO User with Pending Invitation

Setup: Company enables SSO, then sends invitation to employee

Process:

1. Employee receives invitation email
2. Employee logs in via SSO (creates account)
3. Employee must still click invitation link
4. Invitation accepted, role assigned
5. Employee has full access

Note: SSO login alone does not accept the invitation

Scenario 2: User Joining a Second Workspace

Setup: User in Workspace A receives invitation to Workspace B

Process:

1. User clicks invitation link from Workspace B
2. User logs in with their existing account
3. Added to Workspace B with the role from the invitation
4. Membership in Workspace A is unchanged
5. User switches between the two workspaces with the workspace switcher

Scenario 3: Expired Invitation Renewal

Setup: User doesn’t accept invitation within 24 hours

Process:

1. Original invitation expires
2. Admin deletes expired invitation
3. Admin sends new invitation
4. User has another 24 hours to accept

Email Case-Sensitivity

Emails are case-insensitive per RFC 5321. Skycloak normalizes all invitation emails to lowercase before storage. However, be aware of the system behavior:

• Keycloak looks up emails case-insensitively
• Database lookups are case-sensitive by default in PostgreSQL

All invitation emails are normalized to lowercase at creation time to prevent mismatches. If you encounter issues with email matching, ensure the email was entered consistently.

Invitation Cleanup

When Invitations Are Deleted

Invitations are automatically deleted when:

• User accepts - Status changes to accepted, record retained for audit
• Admin cancels - Invitation deleted from pending list
• User deletes account - All invitations to that email are deleted

Orphan Cleanup on Cancellation/Decline

When an invitation is cancelled or declined, the system checks whether the invited user’s Keycloak account is “orphaned” (exists in Keycloak but has no corresponding database record). If so, the Keycloak account is automatically deleted. This prevents leftover Keycloak accounts from accumulating for users who never completed signup.

When Invitations Are NOT Deleted

Invitations remain when:

• Member removed from workspace - Old invitations not cleaned up
• Invitation expires - Remains in system as expired
• Email address changes - Invitations sent to old email remain

Best Practices

For Administrators

1. Communicate clearly - Tell invitees to check email and accept
2. Set expectations - Explain that manual acceptance is required
3. Monitor pending - Check pending invitations regularly
4. Clean up expired - Remove expired invitations periodically
5. Use correct roles - Assign appropriate role in invitation

For Invitees

1. Accept promptly - Invitations expire in 24 hours
2. Check spam folder - Invitation emails may be filtered
3. Use invitation link - Don’t try to join workspace directly
4. Verify email first - Complete email verification if required

Troubleshooting

“I logged in with SSO but don’t have access”

Cause: SSO login doesn’t auto-accept invitations

Solution:

1. Check email for invitation
2. Click the invitation link
3. Complete acceptance flow

“Invitation link shows ‘already accepted’”

Cause: Invitation was previously accepted

Solution:

1. Try logging in normally
2. Check if already member of workspace
3. Contact admin if access issues persist

“Can’t accept invitation - wrong email”

Cause: Logged in with different email than invitation

Solution:

1. Logout of current account
2. Login with invited email address
3. Click invitation link again

“Role not updating after acceptance”

Cause: Session cache delay

Solution:

1. Wait 5 minutes for session refresh
2. Refresh browser (Ctrl+F5)
3. Check event logs for role assignment

Security Considerations

Token Security

• Invitation tokens are cryptographically secure
• Single-use tokens prevent replay attacks
• 24-hour expiration limits exposure window
• Tokens tied to specific email address

Email Verification

• Required for email/password users
• Skipped for SSO users (pre-verified by IdP)
• Prevents unauthorized account creation
• Ensures invitation reaches intended recipient

Audit Trail

All invitation events are logged:

• Invitation created
• Invitation sent
• Invitation accepted
• Role assigned
• Workspace joined

FAQ

Q: Can I accept an invitation without clicking the link? A: No, manual acceptance via the invitation link is always required.

Q: What happens to pending invitations if I delete my account? A: All invitations sent to your email address are automatically deleted.

Q: Can I belong to multiple workspaces? A: Yes. Accepting an invitation adds a workspace membership without removing existing ones, and you can switch between workspaces at any time. Self-service creation is still limited to one workspace per user; additional memberships come from invitations.

Q: Do SSO users need to accept invitations? A: Yes, SSO users must also manually accept invitations by clicking the link.

Q: What happens to invitations when removing a workspace member? A: The membership is removed but any historical invitation records remain for audit purposes.

Q: Can I resend an expired invitation? A: No, you must delete the expired invitation and create a new one.

Related Documentation

• Team Management
• Workspace SSO
• Workspace Security
• User Roles and Permissions