docs/user-facing/communication-and-security/keycloak-account.md

# Managing Your Account & Passkeys

Your account across **The Nest** is managed by **Keycloak**, our central identity and access platform. Keycloak acts as the digital keyring for all services, ensuring your login experience is seamless, consistent, and passwordless.

---

## What Keycloak Does

Keycloak works behind the scenes to handle three core functions:

* **Single Sign-On (SSO):** Log in once to gain access to all connected Nest applications (such as Matrix, Forgejo, or Vaultwarden).
* **Passwordless Authentication:** Securely verifies your identity using WebAuthn passkeys instead of traditional passwords.
* **Group Access Control:** Grants or restricts access to specific services based on your account's group memberships.

---

## Managing Your Passkeys

You have full control over your authentication devices! You can view, add, or remove passkeys at any time directly from your account dashboard.

### Viewing Your Enrolled Passkeys
1. Visit [sso.mynest.love](https://sso.mynest.love) and sign in.
2. Click on **Account** (or navigate to **Security Devices**).
3. Here, you will see a list of all devices and passkeys currently linked to your account.

### Adding a New Passkey
1. From your Keycloak account page, navigate to **Security Devices** and click **Add**.
2. Follow your browser or device prompts to register your new passkey (e.g., a smartphone, security key, or browser password manager).
3. Give your passkey a recognizable name (such as *"Work Laptop"* or *"Personal iPhone"*) to keep track of your devices easily.

### Removing a Passkey
* To remove an old device, locate it under **Security Devices** and select **Delete**.
* **Safety Feature:** Keycloak prevents you from deleting your final remaining passkey to ensure you don't lock yourself out. You must enroll a replacement passkey before removing the last one.

---

## Group-Based Permissions

Your access to different applications across The Nest is managed through **Keycloak Groups**. In most cases, group names match the service they unlock (for example, belonging to the `foundry-vtt` group gives you access to Foundry VTT).

To request access to additional services, please see the [Requesting Service Access](../access-requests.md) guide.

---

## Account Recovery

If you lose access to all of your enrolled devices or passkeys:

1. Reach out to an administrator on Matrix at `@nest:starling.mynest.love`.
2. Verify your identity using the email address linked to your account.
3. An administrator will send you a secure recovery link to reset your credentials and register a new passkey.

---

## Related Services

Here are a few core platforms that integrate directly with Keycloak:

* **[Matrix](../communication-and-security/matrix.md):** Unified chat and voice login via SSO.
* **[Vaultwarden](../communication-and-security/vaultwarden.md):** Can store and manage passkeys securely across devices.
* **[Forgejo](../productivity-and-creation/forgejo.md):** Seamless identity management for code repositories.

---

> [!NOTE]
> *Screenshots of the Keycloak Security Devices page will be added in a future update!*