Environment variables
The complete reference. Values come from .env; the authoritative list is
.env.example plus config/cbox-id.php (this app) and the framework config it
merges from (cboxdk/laravel-id). Run php artisan cbox-id:doctor any time to have
the security-critical ones checked for you.
| Variable |
What it does |
Default |
When to change |
CBOX_ID_CRYPTO_KEY |
base64 of 32 random bytes — the master key for envelope encryption of sealed secrets (signing keys, connection creds). |
(none — generated by cbox-id:install) |
Set once at install. Never rotate casually — it decrypts existing sealed data. Back it up separately from the DB; losing it makes sealed secrets unrecoverable. See Operations. |
CBOX_ID_ISSUER |
The public HTTPS URL of this IdP — the token iss and OIDC discovery base. |
falls back to APP_URL |
Set to the exact public URL clients discover, e.g. https://id.acme.com. |
CBOX_ID_WEBAUTHN_RP_ID |
Passkey Relying-Party ID — usually the registrable domain. |
localhost (in .env.example) |
Set to your bare domain in production, e.g. id.acme.com. |
CBOX_ID_WEBAUTHN_ORIGIN |
Passkey origin — the exact scheme+host+port the browser reports. |
${APP_URL} |
Set to the full origin, e.g. https://id.acme.com. A mismatch is rejected. |
Environments (multi-plane hosting)
An environment is the hard identity boundary — its own users, signing keys, and
issuer — resolved per request from the host.
| Variable |
What it does |
Default |
When to change |
CBOX_ID_ENVIRONMENT_DEFAULT |
The fallback environment (plane) key used when the request host maps to none. |
(empty) |
Set it for a single-tenant / on-prem install (all traffic lands on one plane). Leave empty for multi-tenant hosting, where an unknown host is refused rather than defaulted. |
CBOX_ID_ENVIRONMENT_BASE_DOMAINS |
Comma list of base domains under which a leading subdomain label resolves to an environment (e.g. staging.auth.example.com → the staging plane). |
(empty) |
Set when you host multiple planes as subdomains. A host is trusted for slug resolution only if it sits under one of these, so a spoofed Host can never select a plane. Leave empty to require exact custom-domain matches. Deployment-critical for multi-environment hosting. |
Self-service signup
| Variable |
What it does |
Default |
When to change |
CBOX_ID_SIGNUP_MODE |
Who may self-register at /signup: open (anyone), invite_only (public signup closed, admin invitations still work), or closed (no self-service at all). Admin/operator provisioning is never gated by this. |
open |
Set to invite_only or closed for a private/internal deployment. See Security. |
Enterprise self-serve (SSO, SCIM & Admin Portal)
Gate the self-serve SSO/SCIM screens on a billing-fed entitlement, and tune the
external IT-admin setup link. See
Enterprise self-serve for the full
story.
| Variable |
What it does |
Default |
When to change |
CBOX_ID_ENTITLEMENT_SSO |
The namespaced entitlement key whose enabled flag unlocks self-serve SAML/OIDC SSO for an org. Deny-by-default: without it, the SSO screen shows an upsell and its actions abort(403). |
cbox-id-sso |
Change only to align with the key your billing system pushes. The cbox-id- prefix keeps it from clashing with entitlements your tenant products push through the same projection. |
CBOX_ID_ENTITLEMENT_SCIM |
The namespaced entitlement key whose enabled flag unlocks self-serve SCIM directory sync. Deny-by-default, same as SSO. |
cbox-id-scim |
As above. |
CBOX_ID_PORTAL_TTL_MINUTES |
How long a minted Admin Portal setup link stays redeemable, in minutes. Links are single-use and only their token hash is stored. |
30 |
Lower it for a tighter window; raise it if your customers' IT teams need longer to act. |
Branding
Override the wordmark/hero without editing Blade.
| Variable |
What it does |
Default |
When to change |
CBOX_ID_BRAND_NAME |
Replaces "Cbox ID" in the wordmark and page titles. |
Cbox ID |
Set to your product name. |
CBOX_ID_BRAND_TAGLINE |
The sign-in hero headline. |
One identity layer for every app you ship. |
Set to your own tagline. |
CBOX_ID_BRAND_TRUST_LINE |
Free text under the hero (e.g. a compliance note). |
(empty — on purpose) |
Set only if the claim is actually true for your deployment. Never ship an unearned certification badge. |
Sessions
Session lifetime knobs applied by the identity engine (in addition to the standard
Laravel SESSION_* keys below).
| Variable |
What it does |
Default |
When to change |
CBOX_ID_SESSION_TTL_MINUTES |
Absolute session lifetime before re-authentication. |
480 (8h) |
Lower it for higher-assurance deployments. |
CBOX_ID_SESSION_IDLE_MINUTES |
Idle timeout — inactivity before the session is invalidated. |
30 |
Lower it for shared or high-risk environments. |
OAuth / OIDC endpoint policy
| Variable |
What it does |
Default |
When to change |
CBOX_ID_DCR_MODE |
Dynamic Client Registration (RFC 7591) mode. Controls whether clients (e.g. MCP clients) may self-register. |
disabled |
Enable when you need self-registration; pair with CBOX_ID_DCR_INITIAL_ACCESS_TOKEN for gated registration. |
CBOX_ID_DCR_INITIAL_ACCESS_TOKEN |
Bearer token required to register a client when DCR is gated. |
(none) |
Set when DCR is enabled but should not be open. |
CBOX_ID_REQUIRE_PAR |
Require Pushed Authorization Requests (RFC 9126) — clients must push params server-side instead of via the front channel. |
false |
Set true to harden the authorization endpoint for FAPI-style deployments. |
CBOX_ID_WEBAUTHN_USER_VERIFICATION |
Require user verification (PIN/biometric) during the passkey ceremony. |
true |
Rarely changed; leave on. |
CBOX_ID_EMBED_ENTITLEMENTS |
Embed entitlement claims into issued tokens. |
true |
Disable if consumers resolve entitlements out-of-band. |
Webhooks
| Variable |
What it does |
Default |
When to change |
CBOX_ID_WEBHOOKS_VERIFY_URL |
SSRF-guard + verify webhook target URLs before delivery. |
true |
Keep on. Only relax in isolated test setups. |
CBOX_ID_WEBHOOKS_MAX_ATTEMPTS |
Max delivery attempts before a webhook is marked failed. |
12 |
Raise/lower to match your retry tolerance. |
CBOX_ID_WEBHOOKS_SCHEDULE_RETRIES |
Let the scheduler re-drive failed deliveries. |
true |
Requires schedule:run from cron; keep on in production. |
Risk scoring
| Variable |
What it does |
Default |
When to change |
RISK_MODE |
cboxdk/laravel-risk operating mode: monitor (score and log only) or an enforcing mode (challenge/reject). |
monitor |
Risk blocking is OFF by default — scores are recorded but nothing is challenged or rejected until you switch this to an enforcing mode. Change it once you've reviewed the scores your traffic produces. |
Reverse proxy
| Variable |
What it does |
Default |
When to change |
TRUSTED_PROXIES |
Which proxies' X-Forwarded-* headers to trust (* = trust all, or a comma-separated CIDR list). Correct forwarding makes the audit trail record the real client IP, keys rate limiting on it, and gets the issuer/cookie host right. |
* |
* is safe only when the app is reachable exclusively through your ingress (e.g. a k8s pod behind Traefik/Cloudflare). If the app is directly reachable, pin this to your proxy CIDR(s). |
Security posture (defaults you should keep)
These make the deployment safe to expose. cbox-id:doctor flags any that regress in
production.
| Variable |
Ship as |
Why |
APP_DEBUG |
false |
Debug pages leak stack traces, config and secrets. |
APP_ENV |
production |
Enables the hardening checks and disables dev affordances. |
SESSION_SECURE_COOKIE |
true |
Cookies only over HTTPS — this is a login surface. |
SESSION_ENCRYPT |
true |
Encrypt session payloads at rest in the store. |
SESSION_SAME_SITE |
strict |
Mitigates CSRF (relax to lax only if a cross-site OIDC redirect flow needs it). |
HASH_DRIVER |
argon2id |
Memory-hard, side-channel-resistant password hashing (this app's default, overriding the framework's bcrypt default). Requires sodium/argon2 support. |
SESSION_DRIVER |
redis (recommended) |
Central, revocable sessions; enables sign-out-everywhere and idle timeout. |
Standard Laravel keys
The usual APP_KEY, DB_*, REDIS_*, MAIL_*, QUEUE_CONNECTION, CACHE_STORE
apply as in any Laravel app. APP_KEY is required and distinct from
CBOX_ID_CRYPTO_KEY — the former protects Laravel's own encryption/cookies, the
latter protects the identity platform's sealed secrets. Both must be backed up;
neither is recoverable if lost.
Signing keys are not env vars
Signing keys live in the database, are minted on install/first use, and are rotated
with cbox-id:keys:rotate (see Operations). The
public half is published at /.well-known/jwks.json.
Optional subsystems
- Risk scoring (
cboxdk/laravel-risk) — bot/abuse scoring on signup/login.
Ships in monitor mode (RISK_MODE, above); see the package docs to enforce.
- Social/enterprise SSO — Socialite + connection config per organization;
managed from the admin console, not env.
Where to go next
- Operations — key backup/rotation, upgrades,
break-glass.
- Framework config reference:
config/cbox-id.php in the cboxdk/laravel-id
package
(installation guide).