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

One Workspace Per User

Users can only belong to one workspace at a time. This means:

• Accepting a new invitation removes you from your current workspace
• You cannot be a member of multiple workspaces simultaneously
• Switching workspaces requires leaving the current one first

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. Confirm workspace switch (if applicable)
4. Invitation accepted
5. Joined to new workspace with assigned role
6. Session updated with 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 Switching Workspaces

Setup: User in Workspace A receives invitation to Workspace B

Process:

1. User clicks invitation link from Workspace B
2. System shows warning about leaving Workspace A
3. User confirms switch
4. Removed from Workspace A
5. Added to Workspace B with new role

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

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

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: No, users can only belong to one workspace at a time.

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