# Account & security

Sign in, recover access, change your password, manage sessions and set up an authenticator with recovery codes.

GroCMS 0.1.0 · Workspace · Everyone with a CMS account · Reviewed 15 September 2026

## Sign in to the correct workspace

Open /login on the installation you were invited to use and enter your email and password. The CMS uses email-and-password authentication with optional authenticator verification. Your account is created by an administrator’s invitation or the operator’s first-administrator setup, not by public self-registration.

There is no shared universal administrator password in the application. Use the credentials generated for your installation or the password you chose when accepting an invitation. A developer server and a production preview may have different databases. Check the full address, including the port, before concluding that a valid password has stopped working.

Select Forgot password on the sign-in screen if you need recovery. The acknowledgement deliberately does not reveal whether an account exists. For an eligible enabled account, the application sends a reset link that expires after one hour. A disabled account requires administrator help; password reset does not re-enable it. Repeated requests may be rate-limited.

Sources: Sign-in, reset and MFA forms (repository: `apps/cms/src/cms/auth/forms.tsx`); Authentication configuration (repository: `apps/cms/src/cms/auth/server.ts`); Provisioning and account state (repository: `apps/cms/src/cms/auth/people.ts`); [Better Auth: Email & Password](https://better-auth.com/docs/authentication/email-password).

## Change your password and review sessions

1. Choose your name at the bottom of the sidebar to open Account. This screen shows your name, email and role; it does not provide an ordinary edit-name or change-email form.
2. Under password controls, enter your current password and a new password of 12–128 characters, then choose Update password. The other sessions are signed out.
3. Inspect the signed-in sessions. Device descriptions come from browser information and are approximate; use dates and your knowledge of your devices to identify them.
4. Sign out a session you no longer need, or sign out all other sessions. Use Sign out of GroCMS to end this browser’s session.

An administrator can also revoke sessions from People. Changing a person’s role or disabling their account invalidates existing sessions. If you are unexpectedly asked to sign in again after an access change, that is the intended behaviour.

Sources: Account security interface (repository: `apps/cms/src/cms/auth/security-panel.tsx`); Provisioning and account state (repository: `apps/cms/src/cms/auth/people.ts`).

## Enable an authenticator

1. Open Account and the authenticator setup controls. Confirm your current password and choose Set up authenticator.
2. Copy the displayed setup key into an authenticator application using its manual time-based account setup. This interface provides a key rather than a QR-code scanning screen.
3. Save the recovery codes somewhere you can reach if you lose the phone. They are sensitive credentials and each can be used once.
4. Enter the six-digit code currently shown by your authenticator and select Verify and enable. Confirm that you have saved the recovery codes.
5. At your next sign-in, enter the password and the requested authenticator code. If the device is unavailable, choose Use a recovery code and enter an unused code.

The application uses Better Auth’s two-factor capability with time-based codes and recovery codes. Enabling MFA is a per-account action; the People screen shows whether an authenticator is enabled. The current interface does not offer a workspace-wide policy to require MFA for every account.

Sources: Account security interface (repository: `apps/cms/src/cms/auth/security-panel.tsx`); Sign-in, reset and MFA forms (repository: `apps/cms/src/cms/auth/forms.tsx`); Authentication configuration (repository: `apps/cms/src/cms/auth/server.ts`); [Better Auth: Two-Factor Authentication](https://better-auth.com/docs/plugins/2fa).

## Resolve common access problems

| Problem | What to check |
| --- | --- |
| No reset or invitation email | Check the address and spam folder. Ask the operator to check SMTP delivery. Development Mailpit captures mail locally and does not send it to a real inbox. |
| Authenticator code rejected | Check the device clock and use the current code before it changes. Try an unused recovery code if the device is unavailable. |
| Invitation no longer works | Ask an administrator for a fresh invitation. It may have expired, been cancelled, been replaced or already been accepted. |
| Correct account cannot access a screen | Check the account role and ownership rules. Authentication establishes identity; it does not grant all workspace permissions. |
| Lost authenticator and all recovery codes | Contact the installation administrator/operator. The UI does not supply an unauthenticated bypass or a universal emergency code. |

To disable your own authenticator while you still have access, use the account screen’s disable controls and confirm your password. Treat setup keys, recovery codes, preview links and session tokens as private. The documentation deliberately contains no real account passwords or installation secrets.

Sources: Account security interface (repository: `apps/cms/src/cms/auth/security-panel.tsx`); Sign-in, reset and MFA forms (repository: `apps/cms/src/cms/auth/forms.tsx`); Authentication configuration (repository: `apps/cms/src/cms/auth/server.ts`); Provisioning and account state (repository: `apps/cms/src/cms/auth/people.ts`).

## References

- Account security interface — repository path: `apps/cms/src/cms/auth/security-panel.tsx`

- Sign-in, reset and MFA forms — repository path: `apps/cms/src/cms/auth/forms.tsx`

- Authentication configuration — repository path: `apps/cms/src/cms/auth/server.ts`

- Provisioning and account state — repository path: `apps/cms/src/cms/auth/people.ts`

- [Better Auth: Email & Password](https://better-auth.com/docs/authentication/email-password). Library background; the GroCMS configuration determines its actual password and recovery rules.

- [Better Auth: Two-Factor Authentication](https://better-auth.com/docs/plugins/2fa). Library background for time-based codes and recovery codes; see local source for the enabled interface.

## Related guides

- [Getting started](https://grocms.com/docs/getting-started)

- [People & permissions](https://grocms.com/docs/people)

- [Local setup](https://grocms.com/docs/local-setup)

- [Troubleshooting](https://grocms.com/docs/troubleshooting)