Configure
Authentication
Every way to sign in, who can get an account, sessions and cookies, emailed codes, single sign-on, verified domains and the limits around them.
CirCI uses better-auth for accounts and sessions. There is no self sign-up: every account is created by someone who already has the right to, and every way in is checked against what the instance and the workspace allow. This page is the whole picture. For the first account, see Sign in and set up; for what a person does on their own account, see Account settings.
Sign-in methods
Section titled “Sign-in methods”| Method | What it is | Turned on by |
|---|---|---|
| Password | Email and password, at least 12 characters | On by default. AUTH_PASSWORD_ENABLED or Instance settings |
| Email code | A 6-digit code mailed to the address | Needs SMTP. AUTH_EMAIL_ENABLED or Instance settings |
| Instance single sign-on | GitHub, Google, GitLab, or one generic OpenID Connect provider, shown as buttons | The AUTH_* variables below. AUTH_SSO_ENABLED or Instance settings |
| Workspace single sign-on | A workspace's own OpenID Connect provider | An owner or admin of the workspace, in its settings |
The password switch is read at every sign-in request, so turning it off needs no restart. With it off, a password sign-in is refused with "Password sign-in is turned off on this instance." Each workspace can also narrow the methods people may use to open it: see Workspace settings. The instance sets the outer limit.
Instance providers
Section titled “Instance providers”Each provider is configured by a pair of variables. A half-set pair stops the server at start with one line naming the problem.
| Provider | Variables | Trusted for email |
|---|---|---|
| GitHub | AUTH_GITHUB_CLIENT_ID, AUTH_GITHUB_CLIENT_SECRET |
Yes |
AUTH_GOOGLE_CLIENT_ID, AUTH_GOOGLE_CLIENT_SECRET |
Yes | |
| GitLab | AUTH_GITLAB_CLIENT_ID, AUTH_GITLAB_CLIENT_SECRET, optional AUTH_GITLAB_URL for a self-managed GitLab (default gitlab.com) |
No |
| OpenID Connect | AUTH_OIDC_ISSUER, AUTH_OIDC_CLIENT_ID, AUTH_OIDC_CLIENT_SECRET (all three), optional AUTH_OIDC_NAME for the button label (default "Single sign-on") |
Only with AUTH_OIDC_TRUSTED_FOR_EMAIL=true |
AUTH_OIDC_ISSUER must start with http:// or https://. The callback address to register at a provider is <PUBLIC_URL>/api/auth/callback/<id>, where the ID is github, google, gitlab or oidc.
Trusted for email means the operator vouches that the provider only reports addresses its users own. It decides two things: whether a login may attach to an existing account with the same address, and whether it counts toward joining a verified email domain. GitHub reports a primary address only when it is verified. A self-managed GitLab need not confirm addresses, so it isn't trusted. A login with a provider that isn't trusted can't attach to an account that already existed (except one created less than a minute earlier by that same login); it is refused with "This sign-in provider isn't trusted to link to an existing account".
Who can get an account
Section titled “Who can get an account”Signing in with a provider doesn't create an account by itself. The ways an account comes to exist:
| How | Condition |
|---|---|
| An instance admin creates it | From Instance › Accounts or circi admin user create. See Instance administration |
| An emailed code | The address has a pending invitation, or is on a domain some workspace has verified. Anyone else gets no mail and the same answer as everyone |
| Instance single sign-on | The address has a pending invitation, or the provider is trusted for email, reports the address as verified, and the address is on a verified workspace domain. Otherwise "No account for this address" |
| A workspace's own single sign-on | The workspace's provider brings its people in as members of that workspace. The account starts out unverified |
| First-run setup | The first account, with the setup code |
When a code creates an account and no name comes with it, the part of the address before the @ is used until the person sets one. Names from a provider are trimmed and shortened rather than refused.
Who may create a workspace is the Who can create workspaces instance setting (WORKSPACE_CREATION): admin (the default, instance admins only) or anyone. Someone signed in through a workspace's own provider belongs to that workspace only and can't create workspaces.
Passwords
Section titled “Passwords”A password is at least 12 characters, both when someone sets it and when an instance admin creates the account. Changing it needs the current password, and the new one must be different from it ("The new password must be different from the current one."). CirCI has no "forgot password" flow. A person who lost theirs signs in with an emailed code (and changes the password from their profile), or an instance admin resets it: the new password is shown once and every session of the account is ended.
Email codes
Section titled “Email codes”- A code is 6 digits, valid for 10 minutes, usable once, and stored hashed.
- It locks after 5 wrong attempts.
- Each address may ask for 5 codes per 15 minutes, counted across all client addresses and for addresses with or without an account, so a refusal never tells which addresses exist. A refused request says "Too many sign-in codes requested for this address. Try again later."
- The mail also carries a link that opens the sign-in page with the code filled in. The code travels in the URL fragment, so servers and proxies never see it, and the page still needs a click, so a mail scanner that opens links can't use the code up.
- Mail is sent in the background, so how long it takes says nothing about whether an account exists. A banned account gets no code and the same answer.
- Only the two paths the dashboard uses exist (request a code, sign in with a code), and only while email sign-in is on. Every other path of better-auth's code feature answers "not found".
Without mail on the server, email codes can't be switched on, invitations can't be sent, and an email address can only be changed by an instance admin.
Single sign-on for a workspace
Section titled “Single sign-on for a workspace”An owner or admin connects the workspace's own OpenID Connect provider in Settings › Sign-in and domains (see Workspace settings). What the code guarantees:
- The issuer address must be a public
httpsaddress, with the same private-address rules as a webhook (WEBHOOK_ALLOW_PRIVATE_ADDRESSESlifts them, and then plainhttpis allowed too). CirCI fetches the issuer's/.well-known/openid-configurationwhen you save, and refuses an address with no valid discovery document, or one that doesn't answer. - The provider ID is
<workspace slug>-sso, with the scopesopenid,emailandprofile, and PKCE on. The redirect address to register is<PUBLIC_URL>/api/auth/sso/callback/<workspace slug>-sso. - A workspace can register up to 3 providers.
- Identities are matched by provider and subject, never by email. A login whose address already belongs to another account is refused ("That address already has an account. Sign in the way you did before.").
- New accounts join that workspace only, as members. The session they get opens that workspace only.
- The client secret is stored with the provider and never sent back.
- A provider an instance admin registered has no workspace and behaves like the instance-wide ones.
Verified email domains
Section titled “Verified email domains”A workspace can claim a domain such as example.com so people with an address there join without an invitation.
- An owner or admin adds the domain. CirCI shows a DNS TXT record: the name
_circi-verify.<domain>and the valuecirci-verify=<token>. - Check now looks the record up. A missing record is "not yet", not an error, since DNS takes time to spread. A value split into chunks by the DNS server is joined before comparing.
- Once verified, the domain can only belong to one workspace: another workspace verifying it is refused ("… is already verified by another workspace").
Anyone whose address is on a verified domain joins that workspace as a member when:
- they sign in with an emailed code (the code proves they own the address);
- they sign in with a trusted instance provider that reports the address as verified;
- they change their email to such an address and confirm it, or an instance admin changes it.
Joining only ever adds. Someone who moves from one domain to another keeps their memberships. A password sign-in or a workspace's own provider proves nothing about the address, so neither triggers a join. A workspace that switched GitHub or Google off is not joined through them.
Invitations
Section titled “Invitations”Owners and admins invite an address with a role of admin or member. An invitation is valid for 7 days, and arrives by mail. Inviting an address that already has an open invitation replaces it: the earlier link stops working, and the answer says so. A person without an account creates one by signing in with an emailed code. Only an owner can remove an owner ("Only owners can remove an owner."). See Members and roles.
Changing an email address
Section titled “Changing an email address”- The person enters the new address on their profile. It needs mail on the server, and an address another account uses is refused ("That email address is already in use").
- A confirmation link goes to the new address, valid for 1 hour. The old address gets a notice that a change was requested; nothing has changed yet.
- The link must be opened in a browser that is signed in. Without a session it lands on the sign-in page.
- When confirmed, the profile stops showing "Waiting for confirmation", and the person joins workspaces that verified the new address's domain.
There is no second confirmation from the old mailbox, so a person who lost it can still change their address.
Sessions and cookies
Section titled “Sessions and cookies”- Dashboard cookies are named with the prefix
circi. Overhttpsthey get the__Host-prefix (__Host-circi.session_tokenand the others): browsers then accept them only if Secure, with no Domain and Path/, so a hosted site on a subdomain can't set or overwrite them. Over plainhttp(local development) the prefix can't work, and better-auth's defaults apply. - A session lasts 7 days and is extended while it is used: a request more than a day after the last extension (better-auth's
updateAge, 1 day) pushes the expiry 7 days ahead again. Someone who opens the dashboard at least once a week stays signed in; after a week without a request they sign in again. CirCI doesn't change better-auth's defaults and has no setting for either value. - A signed cookie carries the session for 30 seconds, so most requests skip the lookup. The dashboard API still checks on each request that the session exists, so a session ended elsewhere, or a banned account, gets "Sign in to continue".
- A session remembers how it signed in (password, emailed code, instance provider or a workspace's own provider). A workspace that doesn't allow that method answers "not found" to it. Instance admins are never refused by a workspace's method switches.
- A sign-in from a browser an account hasn't been used from sends the owner a "New sign-in to your CirCI account" mail, naming the method, time, browser and address. The account's very first sign-in doesn't send one. The browser is recognized by a hash of its user agent, so two browsers of the same kind count as one.
- People end their own sessions in Account settings; an instance admin can sign an account out everywhere or ban it (Instance administration).
- Changing
BETTER_AUTH_SECRETsigns everyone out.
Limits and origins
Section titled “Limits and origins”- Rate limiting. better-auth limits requests to its endpoints per client address and path. It is on in production (the image sets
NODE_ENV=production) and off otherwise. CirCI doesn't change better-auth's defaults, so in production: password sign-in and the other/sign-in,/sign-up, change-password and change-email endpoints allow 3 requests per 10 seconds; the emailed-code endpoints (sending a code, checking it, signing in with it) allow 3 per 60 seconds; every other auth endpoint allows 100 per 10 seconds. A request over the limit is answered429with anX-Retry-Afterheader. The counts are kept in the memory of each server process, so they reset when it restarts and each process counts on its own. There is no setting for any of this. The client address is the one Fastify resolved: the socket, or the forwarded chain throughTRUSTED_PROXIES. A forgedX-Forwarded-Forheader from a client is replaced, so it changes nothing. If you run behind a proxy, setTRUSTED_PROXIES, or every sign-in shares one address. See TLS and reverse proxy. - Same origin. A request that changes something in the dashboard API must come from the dashboard's own origin (
PUBLIC_URL). A browser request from any other origin gets 403 "This request must come from the CirCI dashboard itself". Requests with noOriginand noSec-Fetch-Site, such as curl, pass. - Trusted origins. Auth lives under
<PUBLIC_URL>/api/auth. Besides the public origin, the only origins better-auth trusts are those of the issuers of registered workspace providers. - Validation messages. Failed validation of a sign-in request is answered as
{ error, fields }, like the rest of the dashboard API.
The setup code
Section titled “The setup code”A fresh install has no accounts, so whoever reached the dashboard first could claim it. First-run setup therefore asks for a setup code: 20 characters derived from BETTER_AUTH_SECRET, printed in the server's log at start, and printed again by circi admin setup-code. Nothing is stored, so every server process agrees. It is checked in constant time. Changing the secret changes the code. See the admin CLI.
Public information the sign-in page reads
Section titled “Public information the sign-in page reads”GET /api/auth-methods is public, since the sign-in page needs it before anyone is signed in. It answers which of password, email code and instance providers are on (with each provider's ID and button label) and whether any workspace has its own provider.