Authentication & 2FA

Secure your sh0 instance with password or Google OAuth login, and add an extra layer of protection with two-factor authentication.

Login Methods

sh0 supports two authentication methods. Both produce a JWT token that is used for all subsequent API requests and dashboard access.

Password Authentication

The default authentication method. On first installation, sh0 creates an admin account with default credentials displayed in the server logs. You should change the password immediately after first login.

curl -X POST https://your-server:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

The response contains a JWT token valid for 30 days:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "usr_abc123",
      "email": "[email protected]",
      "role": "admin"
    }
  }
}

Google OAuth

For sh0 Cloud users, Google Sign-In is available as a login method. This uses Google's OAuth 2.0 flow with ID token verification via JWKS.

1. Click Sign in with Google on the login page.
2. Authenticate with your Google account.
3. sh0 verifies the ID token and creates or links your account.

Enabling Two-Factor Authentication

Two-factor authentication (2FA) adds an extra layer of security by requiring a time-based one-time password (TOTP) in addition to your regular credentials.

1. Navigate to Settings → Security in the dashboard.
2. Click Enable 2FA.
3. Scan the QR code with an authenticator app (Google Authenticator, Authy, 1Password, etc.).
4. Enter the 6-digit code from your authenticator app to verify setup.
5. Save your backup codes in a secure location.

Once enabled, every login will require the 6-digit TOTP code after entering your email and password.

curl -X POST https://your-server:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password",
    "totp_code": "123456"
  }'

Backup Codes

When you enable 2FA, sh0 generates 10 single-use backup codes. Each code can be used once in place of a TOTP code if you lose access to your authenticator app.

a1b2c3d4e5
f6g7h8i9j0
k1l2m3n4o5
p6q7r8s9t0
u1v2w3x4y5
z6a7b8c9d0
e1f2g3h4i5
j6k7l8m9n0
o1p2q3r4s5
t6u7v8w9x0

You can regenerate backup codes at any time from Settings → Security → Regenerate Backup Codes. This invalidates all previously generated codes.

Changing Your Password

To change your password:

1. Go to Settings → Profile.
2. Click Change Password.
3. Enter your current password and new password.
4. If 2FA is enabled, you will be prompted for a TOTP code.

Passwords are hashed with Argon2id before storage. sh0 enforces a minimum password length of 8 characters.

Session Management

sh0 uses JWT tokens for session management. Tokens are valid for 30 days by default. You can view and manage active sessions from the dashboard.

From the Sessions panel, you can:

• View active sessions: See all devices and browsers where you are logged in.
• Revoke a session: Invalidate a specific session (e.g., if you left yourself logged in on a shared computer).
• Revoke all sessions: Log out everywhere. Useful if you suspect your credentials were compromised.

curl -X DELETE https://your-server:9000/api/auth/sessions \
  -H "Authorization: Bearer YOUR_TOKEN"