Sign-in and security
Password and OAuth sign-in, two-step sign-in, passkeys, rate limits, and the roles and permissions inside a workspace.
Sign-in is handled by Better Auth under /api/auth. The console asks GET /api/auth-methods which options to show, so the sign-in page only offers what the server has configured.
Sign-in methods
Email and password
Password sign-in is on by default, and the sign-in page links to Create an account. Passwords need at least 8 characters.
When you configure an OAuth provider, password sign-in turns off unless you set AUTH_PASSWORD=true. AUTH_PASSWORD=false turns it off in every case. With password sign-in off, the Create account page redirects to sign-in.
Anyone who can open your server’s sign-in page can create an account, but only the first account can create a workspace on an empty server. After that, only admins of an existing workspace can create more; everyone else joins by invitation from an admin and sees a note to ask an admin until then.
Google, GitHub and Microsoft
Create an OAuth app with each provider and set its client ID and secret:
| Provider | Variables | Callback URL to register |
|---|---|---|
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET |
<BETTER_AUTH_URL>/api/auth/callback/google |
|
| GitHub | GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET |
<BETTER_AUTH_URL>/api/auth/callback/github |
| Microsoft | MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET |
<BETTER_AUTH_URL>/api/auth/callback/microsoft |
For example, with BETTER_AUTH_URL=https://help.example.com, the Google callback is https://help.example.com/api/auth/callback/google.
A provider is offered only when both its ID and secret are set. The buttons read Continue with Google, Continue with GitHub and Continue with Microsoft.
AUTH_PROVIDERS limits which configured providers are shown, for example AUTH_PROVIDERS=github. Use it to keep a provider hidden until its app accepts this host’s callback URL.
Accounts with the same email are linked automatically only for Google, which always returns verified emails. GitHub and Microsoft sign-ins link to an existing account only when the provider reports the email as verified.
Any OAuth 2.0 or OpenID Connect server
Your own login server (Keycloak, Authentik, Okta, an in-house SSO) is offered as one more button, Continue with followed by OAUTH_NAME (default “SSO”). Set OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET, then either:
OAUTH_DISCOVERY_URLfor OpenID Connect, for examplehttps://id.example.com/.well-known/openid-configuration. Scopes default toopenid email profile.OAUTH_AUTHORIZATION_URL,OAUTH_TOKEN_URLandOAUTH_USERINFO_URLfor plain OAuth 2.0. No scopes are requested unless you setOAUTH_SCOPES.
Register <BETTER_AUTH_URL>/api/auth/callback/sso as the callback. If the server already has a different callback registered, put it in OAUTH_REDIRECT_URI and have your proxy send that path to /api/auth/callback/sso with its query string.
Sign-in uses PKCE. The user’s ID is read from sub or id, the name from name, preferred_username or username, and the picture from picture, avatar_url or avatar. An account without an email gets <id>@<userinfo host> so it can still sign in, but cannot accept email invitations. Accounts are not linked to existing ones by email.
AUTH_PROVIDERS refers to this provider as sso.
Email codes
Email me a sign-in code appears on the sign-in page once the server can send email (MAIL_SMTP_URL or the SES settings, see Email). AUTH_LOG_OTP=true offers it without a mailer and logs the codes instead, for local development only. When you configure an OAuth provider, email codes turn off unless you set AUTH_EMAIL_OTP=true, so the provider decides who can sign in. AUTH_EMAIL_OTP=false turns them off in every case. A code is 6 digits, expires after 10 minutes, and is sent from MAIL_FROM. Signing in with a code creates the account if it does not exist yet.
Two-step sign-in
Each person turns this on for their own account under Account security (link at the bottom of the sidebar). It applies to every workspace they belong to.
- Click Turn on. If your account has a password, enter it.
- Scan the QR code with an authenticator app such as Google Authenticator, 1Password or Authy. If you cannot scan it, open Cannot scan? Enter this key instead.
- Enter the 6-digit code and click Confirm.
- Save the 10 backup codes that appear (Copy or Download), then click I saved them. Each backup code works once.
After that, signing in with a password or with Google, GitHub or Microsoft asks for a code on the Two-step sign-in page. Lost your phone? Use a backup code switches to a backup code. Ticking Do not ask again on this device for 30 days trusts the browser.
Signing in with a passkey skips the code, because a passkey is already a strong factor.
On the Account security page, New backup codes replaces all backup codes with 10 new ones, and Turn off turns two-step sign-in off. If the page says to sign out and sign in again first, your session is too old for this change: sign in again and retry.
Passkeys
Under Account security, Passkeys, give the passkey a name and click Add a passkey. Your browser or password manager stores it. Each passkey is listed as Synced or This device only and can be removed.
On the sign-in page, Sign in with a passkey appears when the browser supports passkeys and another sign-in method is configured.
Passkeys are tied to the host name of BETTER_AUTH_URL. If you move Rebutdesk to another domain, existing passkeys stop working and must be added again.
Rate limits
Sign-in endpoints are rate limited per IP address, stored in the database:
| Endpoint | Limit |
|---|---|
| Password sign-in | 5 per minute |
| Account creation | 5 per minute |
| Email code sign-in | 5 per minute |
| Sending an email code | 3 per 5 minutes |
| Passkey sign-in | 10 per minute |
| Other auth endpoints | 100 per minute |
The client IP is read from cf-connecting-ip or x-forwarded-for, so make your reverse proxy set one of them (see Run with Docker).
Roles and permissions
Each member of a workspace has a role:
- Admin: every permission. A workspace always keeps at least one admin.
- Agent: create cases, reply to buyers, add internal notes, and change status, assignee and tags.
- Viewer: read only.
Every member can read the workspace’s cases. On the Team page, an admin (or anyone with “Manage team members”) can change a member’s role, and open Permissions to give an agent or viewer a custom set instead of the role defaults. Changing the role resets custom permissions to the new role’s defaults. Admins always have everything.
| Permission | Label on the Team page | Agent default |
|---|---|---|
cases.create |
Create cases | Yes |
cases.reply |
Reply to buyers | Yes |
cases.note |
Add internal notes | Yes |
cases.update |
Change status, assignee and tags | Yes |
chat.manage |
Change live chat settings | No |
members.manage |
Manage team members | No |
billing.manage |
Manage billing | No |
workspace.manage |
Rename the workspace | No |
payments.manage |
Connect Stripe and PayPal | No |
disputes.manage |
Submit or accept disputes | No |
refunds.create |
Refund payments | No |
workspace.manage covers more than its label: it also controls API keys and webhooks, the AI model and switches, the knowledge base, setup and email mailboxes. cases.update also lets a member prepare and save dispute evidence and record promises.
Adding teammates
Members with “Manage team members” invite people on the Team page under Invite a teammate: enter their email, pick a role and click Invite. Rebutdesk emails them a link when the server can send email; the link is always shown so you can send it yourself.
- The person opens the link, signs in or creates an account with the invited address, and clicks Join. An account with a different email cannot use the link.
- A link works once and expires after 7 days. Inviting the same address again replaces the earlier link; Withdraw cancels it.
- People who are already members cannot be invited again.
Sub-accounts (logins an admin creates with a username, shown as Add a sub-account) are a feature of the hosted cloud; on a self-hosted server that section does not appear.
Next: Email