Laravel Nova Composer auth.json: Local Development Without Committing Credentials

Why Laravel Nova Needs auth.json in the First Place

Laravel Nova isn't distributed through the public Packagist registry — it lives on a private Composer repository at nova.laravel.com, gated behind a paid license. Installing it means adding that repository to composer.json and then authenticating against it, the same way Composer authenticates against any private package source (Satis, Private Packagist, a private VCS repository):

composer require laravel/nova

Without stored credentials, that command fails with a 401 and Composer prompts interactively for a username and password — your Nova account email and license key — then offers to save them to auth.json.

The Problem With Committing auth.json

Composer's default behavior is to write those credentials into auth.json at the project root, right next to composer.json — in exactly the directory that gets committed to Git. Accepting that prompt the first time you install Nova is an easy mistake: the license key ends up in your repository's history, visible to anyone with read access, permanently, even if the file is deleted in a later commit.

What people actually mean by "bypass auth.json" isn't avoiding Nova's licensing check itself — a valid license is still required — it's avoiding that file as the storage location for credentials, so Composer authenticates without anything landing in version control.

Step 1: gitignore It (Baseline, Not a Full Fix)

# .gitignore
/auth.json

This should already be in place — Laravel's default .gitignore includes it — but it only protects one repository going forward. It doesn't help a second developer set the project up, doesn't help CI, and doesn't help after you switch machines.

Step 2: Use the COMPOSER_AUTH Environment Variable

Composer checks the COMPOSER_AUTH environment variable before it ever touches a project's auth.json. Set it as a JSON string and Composer authenticates directly, with no file involved at all:

export COMPOSER_AUTH='{"http-basic":{"nova.laravel.com":{"username":"[email protected]","password":"YOUR-NOVA-LICENSE-KEY"}}}'
composer require laravel/nova

Put that export in a shell profile (~/.zshrc, ~/.bashrc) that's never committed, and every composer install/composer update on that machine authenticates without writing auth.json into the project directory at all.

Using COMPOSER_AUTH With Docker or ddev

For a team running Composer inside a container, the credentials need to reach that container's Composer process without being baked into a shared, committed image. Pass it as a per-developer environment variable instead of a build argument:

# .ddev/config.local.yaml (gitignored override, not the committed config.yaml)
web_environment:
  - COMPOSER_AUTH={"http-basic":{"nova.laravel.com":{"username":"[email protected]","password":"YOUR-LICENSE-KEY"}}}

Keeping this in a gitignored local override file means each developer (or the team's shared license) supplies credentials locally without them ever touching the repository.

A Global auth.json Outside the Project

Composer also checks a global config directory before it looks at the project-local auth.json. Storing credentials there keeps them outside any Git repository entirely:

composer global config http-basic.nova.laravel.com [email protected] YOUR-LICENSE-KEY

This writes to ~/.composer/auth.json (or %APPDATA%/Composer/auth.json on Windows) — a per-machine file that never enters a project's history. It's the simplest option for a solo developer, or a small team where each person authenticates once and keeps working.

CI and Deployment: Secrets, Not Committed Files

The same principle applies to CI pipelines and production builds: set COMPOSER_AUTH as an encrypted/masked secret in whatever platform runs the build (GitHub Actions secrets, GitLab CI variables, your deploy pipeline's environment config) instead of checking an auth.json in alongside the code that gets built.

Common Errors and What They Actually Mean

• 401 Unauthorized on nova.laravel.com — credentials are missing, expired, or the license key was rotated since you last authenticated; re-run the composer global config command with the current key.
• "Could not authenticate against nova.laravel.com" — almost always a typo in the username (it must be the email tied to the Nova license, not an arbitrary value) or a password field still holding an old key.
• Nova installs locally but fails in CI or production — a strong sign that COMPOSER_AUTH (or an equivalent secret) isn't set in that environment; local success often just means a global auth.json is quietly doing the work only on your machine.

The Right Mental Model

There's no way to install genuine Laravel Nova packages without a valid license — Composer is enforcing a real entitlement check, not an arbitrary inconvenience. What you can and should control is where those credentials live: never in a committed auth.json, and instead in COMPOSER_AUTH, a global per-machine config, or your CI provider's secret store.

Setting up Laravel Nova (or any other private Composer package) across a team without leaking credentials into Git? Get in touch — I work as a freelance Laravel developer.