Sign-in
How people sign in to 3AM, how the first owner is created, what the admin token is for, setting up email, and who may sign in.
People sign in one of four ways. Every tier has all of them.
| Way | For | Set up in |
|---|---|---|
| Single sign-on (OIDC) | Entra ID, Okta, Ping, Keycloak, ADFS | Settings → How people sign in (SSO) |
| Directory password (LDAP) | LDAP or Active Directory, where no identity provider is reachable | The same |
| A code by email | Everyone else | Settings → E-mail sign-in |
| A password | One person who can't receive a code, such as an auditor | Team → Password |
The first owner
A new install's sign-in page asks for the admin token the installer printed, and your email. That makes you the owner. The same page lets you add a Resend key, so colleagues can sign in with emailed codes straight away.
Setting up email
Emailed codes need a mail provider. Without one, only the admin token gets in.
| Provider | How |
|---|---|
| Resend | Paste the API key in Settings → E-mail sign-in, or install with --resend-key-file FILE |
| Any SMTP server (SES, Postmark, Microsoft 365, Google Workspace, your relay) | Fill in Settings → E-mail sign-in, or install with --smtp-host H --smtp-user U --smtp-password-file F |
The sender must be on a domain your provider has verified. Resend's sandbox sender only delivers to the Resend account's own address, so verify your domain in Resend first. Send me a test e-mail proves it works before anyone needs a code.
On Kubernetes, use the chart's mail.resendKeySecret or mail.smtp.* values.
How emailed codes work
The person enters their email, and 3AM sends a six-digit code. It works once, for 10 minutes. 3AM gives the same answer whether or not an address has access, so the sign-in page never reveals who's a user.
The admin token
After the first owner, the admin token has two jobs:
- Automation. Scripts and CI can call the API with
Authorization: Bearer <admin token>, with owner rights. - Break-glass. When codes can't be sent, because mail isn't set up or the provider is down, the sign-in page offers the token instead. Each use is logged, and the console shows a banner until mail works again.
Otherwise, the admin token can't be used to sign in.
| Install | Where to find it |
|---|---|
| Linux server | Printed once by the installer. Later: podman cp 3am-core:/var/lib/3am/admin-token - | tar -xO |
| Kubernetes | kubectl -n 3am get secret threeam-admin -o jsonpath='{.data.token}' | base64 -d |
| Your own token | Set THREEAM_ADMIN_TOKEN, or the chart's adminToken.existingSecret |
Who may sign in
Only people an admin has added, or members of your directory's mapped groups. Team → Who may sign in narrows it further:
- Allowed domains. A new install starts with the first owner's domain.
- Blocked domains and addresses, as you choose. Throwaway email services are always refused, and public webmail can be too.
Tightening the rules signs out anyone now outside them, at once. A change that would lock out every owner is refused.
Passwords for one person
For a reviewer, auditor or guest without a mailbox on your domain. Only an owner can give one, and not to another owner or a directory user. The password is shown once, and ends after 7, 30 or 90 days, or never. Five wrong tries lock the address for 15 minutes.
Sessions
A session ends after 12 hours idle, or 7 days, whichever comes first. It also ends when the person signs out, closes the tab, is disabled, or has their role changed.
API
| Call | Who | What it does |
|---|---|---|
POST /v1/auth/request {email} | anyone | Send a code |
POST /v1/auth/verify {email, code} | anyone | Sign in with the code: returns {token, user} |
POST /v1/auth/password {email, password} | anyone | Sign in with a password |
POST /v1/auth/logout | signed in | End this session |
POST /v1/auth/bootstrap {email, name} | admin token | Create the first owner, once |
GET, PUT /v1/settings/mail; POST /v1/settings/mail/test | viewer, admin | The mail provider |
GET, PUT /v1/settings/access | viewer, admin | Who may sign in |
Every sign-in, code and change is recorded in the audit log under identity.* events.
Keyboard shortcuts
Every console shortcut. The command bar, search, going to any page with g, moving through lists, and the rules (Tab, Enter, Escape, arrows) every page follows.
Single sign-on
Let people sign in with your identity provider (OIDC) or directory (LDAP, Active Directory), with roles and teams coming from directory groups.