Authentication
Laravel holds the accounts and decides who gets in. The sign-in and account screens are Flare’s, unchanged, and talk to Laravel through the web app. A signed-in browser keeps a Sanctum token in an httpOnly cookie: the browser sends it, and scripts on the page cannot read it.
What is included
Section titled “What is included”| Password | Sign in, forgot password, reset by an emailed link, change it from the account page. |
| Google, GitHub | Sign in with either, once switched on. Connect and disconnect them from the account page. |
| Two-factor | A code from an authenticator app, or a code by email, after the password. Ten backup codes. |
| Passkeys | Face ID, Touch ID, Windows Hello or a security key. No password to type. |
| Emailed link, emailed code | Sign in from an email, without a password. |
| Email verification | A six-digit code, and a link that carries it. |
| Profile | Name, and a picture that is optimised like any image. |
| Devices | Every browser signed in to the account, and signing them out. |
| Sign-up | Off until you switch it on. See below. |
The pages
Section titled “The pages”| Page | What it is |
|---|---|
/sign-in |
Email first, then a password, a link or a code. A passkey button beside it. |
/two-factor |
The second step, when the account has one. |
/sign-up |
Create an account. Closed unless registration is on. |
/forgot-password, /reset-password |
Ask for a reset link, and choose the new password. |
/verify-email |
Enter the code from the email, or arrive by its link. |
/dashboard/account |
Profile: picture, name, email. |
/dashboard/account/password |
Change the password. |
/dashboard/account/security |
Two-factor, passkeys, and connected Google and GitHub accounts. |
/dashboard/account/sessions |
Devices. |
Creating users
Section titled “Creating users”nevela userIt asks for a name, an email, a password and a role. Pass them as options to skip the questions: nevela user --name="Ada Okafor" --email=ada@example.com --password="…" --role=EDITOR. The first account in an app is its administrator.
People with the permission can also add, change, switch off and delete users from the dashboard’s Users screen: see Users, roles and permissions.
Verified means proved
Section titled “Verified means proved”An email is marked Verified when its owner has proved the address is theirs: by the verification link or code, by signing in with an emailed link or code, or by resetting their password from an email. Nothing else marks it.
So an account you make with nevela user, one an administrator adds on the Users screen, the starter admin@example.com and the sample users all start as Not verified. That is the truth about them. Their owner verifies from Account → Profile, with Send verification link.
This matters only if you set require_email_verification: then an unverified account is sent a link the first time it signs in, and gets in once it has used it. For an account on a server whose address you know is right, and where email isn’t set up yet, say so when you make it:
nevela user --name="Ada Okafor" --email=ada@example.com --role=ADMIN --verifiedLetting people sign up
Section titled “Letting people sign up”Sign-up is off by default: most dashboards are for a team, not for the public.
Someone who signs up gets the USER role, which allows nothing beyond their own account, so opening sign-up doesn’t open your data. An administrator gives them more from the Users screen.
To start sign-ups on a role of your own instead, such as CUSTOMER for a shop that lets people order, make the role on the Roles screen and set NEVELA_DEFAULT_ROLE=CUSTOMER in apps/api/.env. An app that published config/nevela.php sets auth.default_role there. The mobile app gives an account that holds only this role the customers’ app.
To open it:
- Add
NEVELA_REGISTRATION=truetoapps/api/.env. - Run
nevela generate, so the sign-in page shows the link.
To have new accounts prove their address before they can sign in, set require_email_verification to true in config/nevela.php.
Email in development
Section titled “Email in development”Codes and links are sent with whatever mailer your Laravel app is configured with. A new app uses the log mailer, which sends nothing. So in development Nevela also prints each code or link in the terminal where nevela dev is running:
api │ Nevela mail to ada@example.com: Your Laravel sign-in codeapi │ 482913Copy it from there. In production, set MAIL_MAILER and its settings in apps/api/.env as for any Laravel app.
Two-factor
Section titled “Two-factor”From Account → Security, a person can add a second step to password sign-in.
- An authenticator app. They scan a QR code, then type a code from the app to confirm it. Nothing is switched on until that code is right, so a failed setup cannot lock anyone out.
- Email codes. A six-digit code is emailed at each sign-in.
- Backup codes. Ten are shown once, when two-factor is set up. Each signs in one time when the phone is not to hand. They can be replaced, which stops the old ones working.
Turning two-factor on, off, or replacing the backup codes asks for the password again.
When the second step is asked for:
| Signed in with | Account has an authenticator app | Account’s second step is email only |
|---|---|---|
| a password | asked: the app, an emailed code or a backup code | asked: an emailed code or a backup code |
| an emailed link or code | asked: the app or a backup code, not another email | signed in |
| a passkey | signed in | signed in |
An emailed link followed by an emailed code would be the same proof twice, so someone who had only got into the mailbox would be let in. That is why email is not offered as the second step after an email. A passkey is not asked for more: it is something the person has, unlocked by something they are or know.
A code from the app works once. Typing the same six digits again, in the same half minute, is refused.
Passkeys
Section titled “Passkeys”A passkey is a key pair. The private half stays with the person: on one device, or synced between their own devices by their password manager (iCloud Keychain, Google Password Manager and the like). It is never sent to your app. Laravel keeps the public half. To sign in, the device signs a random challenge and Laravel checks the signature.
From Account → Security → Add a passkey, the browser asks the device to create one. After that, Sign in with a passkey on the sign-in page signs in with no email and no password. Browsers that support it also offer saved passkeys in the email field.
Passkeys are tied to the address of the dashboard, so two things have to be true:
- The dashboard is on
https, or onlocalhost. Browsers refuse passkeys anywhere else. - Laravel knows the dashboard’s address: set
NEVELA_WEB_URL(see Going to production).
Google and GitHub
Section titled “Google and GitHub”Off until you switch it on. Everything is in apps/api/.env: no config file to publish, no nevela generate and no rebuild.
-
Get each provider’s keys, a client ID and a client secret. See Getting the keys, below.
-
Put them in
apps/api/.env, with the switch, as in Grit:Terminal window SOCIAL_AUTH_ENABLED=trueGOOGLE_CLIENT_ID=…GOOGLE_CLIENT_SECRET=…GITHUB_CLIENT_ID=…GITHUB_CLIENT_SECRET=… -
Reload the sign-in page. There is a button for each provider with both its keys.
-
Check with
nevela status:Social sign-in .. on: Google (GitHub has no keys).
How it decides:
- The switch turns every provider on or off. Off, no button shows and Laravel refuses the routes.
- A provider shows once both of its keys are set. Set Google’s only, and there is one button. With the switch on and no provider’s keys, there are no buttons. In development the sign-in page says so, and so does
nevela status. - The dashboard asks Laravel which to show on every page. Where the config is cached (
php artisan config:cachein production), runphp artisan config:clearafter changing.env.
It is built on Laravel Socialite.
Getting the keys
Section titled “Getting the keys”Each provider asks for the address to send people back to. It is the dashboard’s, not the API’s:
https://app.example.com/api/auth/oauth/google/callbackhttps://app.example.com/api/auth/oauth/github/callbackIn development, register http://localhost:3000/api/auth/oauth/google/callback as well (and the same for GitHub). If the dashboard moves to another port because 3000 is taken, the address moves with it, so keep 3000 free or register that port too.
Google. In the Google Cloud console, choose Create credentials → OAuth client ID, application type Web application. Add the address above under Authorised redirect URIs. Copy the client ID and secret. The consent screen asks for an app name and a support address the first time.
GitHub. In Settings → Developer settings → OAuth Apps → New OAuth App, set the Authorization callback URL to the address above. Copy the client ID, then generate a client secret.
Who gets in
Section titled “Who gets in”It follows registration:
| Registration off (the default) | Registration on | |
|---|---|---|
| An account here has that address | Signs in, and the provider account is connected to it | The same |
| No account has it | Refused: “There’s no account here for that address” | A new account, with the role new sign-ups get |
An address is matched only if the provider says it is verified. Google says so of each address. GitHub gives only a verified one. A closed account, a switched-off account and a blocked address are refused, as for every other way in.
Once connected, the provider account is found by the provider’s own id for the person, so a later change of address at Google or GitHub doesn’t lose the account.
If the account’s own address was never verified here, the provider is the first to prove it belongs to whoever is signing in. Someone else could have made that account in their name, with sign-up open, so its password stops working and every device signed in to it is signed out. The owner carries on with the provider, or sets a new password with Forgot password. An account whose address was verified keeps its password.
An account made this way has a password nobody knows. Its owner signs in with the provider, or sets a password with Forgot password.
Two-factor still applies. An account with an authenticator app is asked for it after the provider, as after a password.
Connecting from the account page
Section titled “Connecting from the account page”Account → Security → Connected accounts lists the providers that are on. Connect goes to the provider and back, and connects that provider account to the one signed in. One provider account can be connected to one account here. Disconnect is always allowed: every account has its email address, so there is still a way in by a reset link, a sign-in link or a code.
How it works
Section titled “How it works”The browser never talks to Laravel, and never holds a token:
- The button opens
/api/auth/oauth/googleon the dashboard. Its server asks Laravel where Google’s page is, and sends the browser there. - Laravel makes the state that goes with it, good once for ten minutes. The dashboard keeps it in an httpOnly cookie, so Google’s answer is taken only in the browser that asked. Nobody can sign you in to their own account by sending you a link.
- Google sends the browser back to
/api/auth/oauth/google/callbackon the dashboard. Its server hands the code to Laravel, which asks Google who it is and signs the person in. The token goes into the cookie, as after a password.
From the mobile app
Section titled “From the mobile app”The mobile app has the same buttons. A phone has no dashboard to come back to, so the API has a way back of its own:
- The app asks the API where Google’s page is, and says where to return to (its own address, such as
juice-me://oauth) and gives a challenge: the SHA-256 of a secret it keeps. - Google sends the browser to
{APP_URL}/api/auth/oauth/google/appon the API. The API uses Google’s code there, to ask Google who the person is, so the code goes no further, and hands the browser on to the app’s address with only the state. - The app sends the state and its secret to
/api/auth/oauth/google/callback. The API checks the secret against the challenge and signs the person in. Anyone who takes the state off the phone, or is another app that has claimed the same address, still has no secret, and the code is already used up.
Two things to set up:
- Register that second address with Google, beside the dashboard’s:
{APP_URL}/api/auth/oauth/google/app.APP_URLinapps/api/.envhas to be the API’s public address. Google only returns tohttpsaddresses (and tolocalhost), so this works against a deployed API. It can’t work againsthttp://192.168.…while you develop on a phone: use a tunnel with anhttpsaddress, or an emulator. - List the apps the API may send people to, in
apps/api/.env:NEVELA_APP_REDIRECTS=juice-me://. Comma separated, and the app’s own address has to start with one.nevela new my-app --mobilesets it for the new app’s address. Nothing else is ever sent a code. WhileAPP_ENVislocal, Expo Go’s own address is allowed as well.
The profile picture
Section titled “The profile picture”Uploading a picture on the profile page sends it through the same optimiser as any image field, with the avatar profile: it is turned the right way up, stripped of its metadata, cropped to a 400×400 square in WebP, and given an 80×80 thumbnail for the menus. A 1.2 MB, 4000×3000 photo came out as 37 KB, with a 4 KB thumbnail.
Change the sizes under uploads.profiles.avatar in config/nevela.php.
How long a sign-in lasts
Section titled “How long a sign-in lasts”A sign-in ends on its own, as it does in Grit:
| Default | Setting (apps/api/.env) |
|
|---|---|---|
| An access token works for | 15 minutes | NEVELA_SESSION_ACCESS |
| A sign-in ends when it isn’t used for | 7 days | NEVELA_SESSION_IDLE |
| A sign-in ends, however busy, after | 30 days | NEVELA_SESSION_ABSOLUTE |
| The dashboard warns, with no mouse or keyboard, after | 14 min 30 s, then counts down 30 s | NEXT_PUBLIC_SESSION_IDLE_MS, NEXT_PUBLIC_SESSION_COUNTDOWN_MS (apps/web/.env.local) |
The settings in apps/api/.env are in minutes. For the idle and absolute limits, empty or 0 is no limit. An access token always expires: empty or 0 gives 15 minutes.
- Someone working is never interrupted. A sign-in is a short access token and a refresh token. Before the access token runs out, the dashboard swaps the refresh token for a new pair, so a copy of an access token taken from a browser stops working within 15 minutes.
- A screen left unattended signs itself out. After 14 min 30 s with no mouse, keyboard, touch or wheel, the dashboard asks “Still there?” and counts down 30 seconds. Stay signed in carries on. Otherwise the sign-in ends in Laravel, not only in the browser, and the sign-in page says why. Moving the mouse while it counts doesn’t dismiss it. Working in another tab of the dashboard counts as being there, and signing out in one tab signs the others out.
NEXT_PUBLIC_SESSION_IDLE_MS=0turns the warning off; the server’s limits still apply. - A stolen refresh token gives itself away. Each refresh token is used once and swapped for a new one. If one that was already swapped is used again, however many swaps ago, by a thief or by the person it was taken from, the sign-in ends on every device holding it, and the sign-in page says why. The one exception is a second request that set out with the same token at the same moment, within a minute: it is given an access token and carries on.
- Signing out takes effect at once. From the account menu, from Account → Devices, by an administrator, by changing the password or closing the account: the sign-in’s tokens are deleted, and the next request is refused.
The scheduler removes ended sign-ins each night (nevela:prune-sessions). nevela status shows the limits in use.
Tokens your own code makes with createToken(), and those from before 0.12, belong to no sign-in. They keep to the same idle and absolute limits, measured from when each was last used and when it was made. An app with its own Sanctum::authenticateAccessTokensUsing() replaces that check; Nevela’s own tokens still expire.
Devices
Section titled “Devices”Each sign-in is a device in Account → Devices, with its browser, its address, when it was last used and when it ends if it isn’t used again. The browser and address are what the dashboard reports about the visitor, which Laravel believes because the two share a secret (NEVELA_PROXY_SECRET, written into both apps when the app is created). Someone calling the API directly cannot choose how their device is listed. The page can sign out every other device. Changing the password does the same, and resetting a forgotten password signs out every device, this one included.
Closing an account
Section titled “Closing an account”At the foot of Account → Profile, Close account lets someone close their own. It takes their password, signs them out everywhere, and keeps the account for an administrator to restore or remove for good. Their email can’t sign up again meanwhile. See Deleted accounts, which also says how to switch this off.
Switching methods on and off
Section titled “Switching methods on and off”The choices are in the auth section of config/nevela.php in the Laravel app. Two of them need no file, because they come from apps/api/.env: NEVELA_REGISTRATION and SOCIAL_AUTH_ENABLED. For the rest, write the file:
nevela publish| Key | Default | |
|---|---|---|
registration |
NEVELA_REGISTRATION, false |
People can create their own account. Set it in .env. |
magic_link |
true |
Sign in with an emailed link. |
email_code |
true |
Sign in with an emailed code. |
passkeys |
true |
Passkeys. |
two_factor.authenticator |
true |
An authenticator app as the second step. |
two_factor.email |
true |
Emailed codes as the second step. |
require_email_verification |
false |
Refuse password sign-in until the address is verified. |
check_breached_passwords |
true |
Refuse a new password that appears in a known breach. |
social.enabled |
SOCIAL_AUTH_ENABLED, false |
Signing in with Google and GitHub. Set it in .env, with each provider’s keys. See above: it needs no file and no generate. |
Then run nevela generate. That writes the choices to apps/web/lib/auth-config.ts, so the screens stop offering what is off. Laravel refuses a method that is off whatever the screens show.
Passwords
Section titled “Passwords”A new password needs eight characters. The forms show a strength reading and advice as it is typed, which is advice only: length matters more than punctuation.
Every password box, the one on the sign-in screen included, has an eye at its end that shows what has been typed, and hides it again.
A new password is also checked against Have I Been Pwned’s list of breached passwords, and refused if it is on it. Only the first five characters of the password’s hash leave your server, and if the service cannot be reached the password is accepted.
What protects sign-in
Section titled “What protects sign-in”- Attempts are limited to ten a minute per account, so a password cannot be guessed at speed.
- A code allows five wrong guesses, then it is thrown away. Six codes an hour can be sent to one address.
- Links and codes work once and expire: sign-in links and codes in 5 minutes, reset and verification in an hour.
- Nothing says whether an address has an account. Asking for a reset link, a sign-in link or a code gets the same answer either way, and a wrong password and an unknown address get the same answer in the same time.
- Secrets are not readable in the database. Authenticator secrets are encrypted with the app key, backup codes are stored as hashes, and a passkey’s stored half is public by design.
- Emails only link to your dashboard. The address in a link is the one you configured, never one a request supplied. Where to go after signing in is a path on the dashboard and nothing else.
Going to production
Section titled “Going to production”In apps/api/.env:
# Where the dashboard is. Links in emails point here, and passkeys are tied to it.NEVELA_WEB_URL=https://app.example.com
# A real mailer, as for any Laravel app.MAIL_MAILER=smtpMAIL_FROM_ADDRESS=hello@example.com
# The same value as in the dashboard's environment. See Devices, above.NEVELA_PROXY_SECRET=a-long-random-string
# Only if people sign in with Google or GitHub. Register the production callback address with each.SOCIAL_AUTH_ENABLED=trueGOOGLE_CLIENT_ID=…GOOGLE_CLIENT_SECRET=…And NEVELA_PROXY_SECRET with the same value wherever the dashboard runs. An app created with 0.4.0 or later has one in both .env files already; copy it to your hosts. Without it, a device is listed with the address the request reached Laravel from, which in production is your dashboard’s server.
In development you do not need NEVELA_WEB_URL: any localhost address is accepted, because the dashboard moves to another port when 3000 is taken.
Over the API
Section titled “Over the API”Every endpoint is under /api/auth. The REST API reference lists them. In short, to get a token:
curl -X POST http://127.0.0.1:8000/api/auth/token \ -H 'Accept: application/json' -H 'Content-Type: application/json' \ -d '{"email": "ada@example.com", "password": "…"}'{ "token": "1|…", "expiresAt": "2026-10-20T09:15:00.000000Z", "refreshToken": "kq0…", "refreshExpiresAt": "2026-10-27T09:00:00.000000Z", "user": { "id": "1", "name": "Ada Okafor", "email": "ada@example.com" }}Send the token as Authorization: Bearer <token> on every other request. Before expiresAt, swap the refresh token for a new pair with POST /api/auth/refresh, and keep the new refresh token: the old one won’t work again. If the account has two-factor on, there is no token in that answer yet: see the reference.
How the browser stays signed in
Section titled “How the browser stays signed in”Scripts on the page never see a token. The auth screens call the web app’s own /api/auth/… route, which passes each request to Laravel. When Laravel answers with tokens, the route puts them in httpOnly cookies, which the browser stores and sends but page scripts cannot read, and removes them from the answer:
nevela_token, the access token, lasting a minute less than the token does;nevela_refresh, the refresh token, lasting until the sign-in would end unused.
When the first has gone and the second is there, the web app’s proxy.ts swaps the refresh token for a new pair before the page or API call goes ahead (lib/session-cookies.ts). When Laravel says the sign-in has ended, both cookies go and the page is sent to the sign-in page, which says why. Signing out ends the sign-in in Laravel and removes both cookies.
lib/auth-client.ts in the web app has the browser’s side of this, under the method names Flare’s screens call. That is why the screens could be copied without changes.
Using your own auth
Section titled “Using your own auth”Set auth.enabled to false in config/nevela.php and Nevela registers none of these routes. Provide your own auth:sanctum tokens, or change middleware to the guard you use.