Authenticate ACF PRO with Composer and Eliminate Common 401 Errors

Key points:

• ACF PRO uses a private Composer repository that requires authentication.
  
• HTTP 401 errors occur when Composer can’t authenticate with your ACF PRO license.
  
• Composer expects credentials to be provided securely, outside of composer.json.
  
• Authentication must be handled explicitly in local, CI, and deployment environments.
  
• Once authentication is configured correctly, ACF PRO installs and updates behave consistently.

When Composer fails to download ACF PRO with an HTTP 401 error, it’s rarely a broken license or a transient network issue.

Almost always, it’s an authentication problem.

This guide walks through how ACF PRO Composer authentication actually works, why 401 errors happen, and how to fix them safely across local development, CI, and production — without ever committing your license key to git.

We’ll focus entirely on credential handling and authentication, not on repository setup or installation basics. You’re expected to already have:

• A valid ACF PRO license key
• A working Composer-based workflow
• Familiarity with Composer config files and environment variables

If Composer is rejecting your credentials, this article will help you understand why — and how to resolve it permanently.

One important thing to keep in mind is that Composer authentication is not something you configure once and forget. Any environment that runs Composer — whether that’s your laptop, a CI runner, or a production deployment server — must be able to authenticate successfully before ACF PRO can be installed or updated.

If you’re still getting started with Composer + ACF PRO, follow our guide on installing ACF PRO with Composer.

Why Composer returns a 401 when downloading ACF PRO

A 401 error means Composer reached the ACF servers, but your request was not authenticated, so the repository refused access.

This typically happens for one of four reasons:

1. Composer has no credentials at all
   
2. Credentials are present, but attached to the wrong domain
   
3. Credentials exist, but are malformed or overridden
   
4. Environment-specific authentication (CI, deploys) is missing
   

ACF PRO is distributed via a private Composer repository, which requires HTTP Basic authentication.

Composer will not prompt you interactively in non-interactive contexts, so credentials must be provided explicitly. This is especially important in automated workflows where there is no opportunity to manually enter credentials.

If authentication fails, Composer responds with a 401 and stops.

A typical error might look like:

The 'https://composer.advancedcustomfields.com/...' URL required authentication (HTTP 401)

That message is Composer telling you it successfully connected — but did not receive valid credentials.

How ACF PRO Composer authentication works

ACF PRO uses HTTP Basic Auth, where:

• The username is your ACF PRO license key
  
• The password is left blank
  

Composer needs to know which host those credentials belong to. For ACF PRO, authentication is scoped to:

composer.advancedcustomfields.com

Composer will never embed credentials directly into composer.json. Instead, it reads them from secure external sources such as:

• auth.json
  
• environment variables (COMPOSER_AUTH)
  
• CI/deployment secrets managers
  

Understanding where Composer looks — and which source wins — is the key to eliminating 401 errors permanently.

It’s also worth noting that Composer can load authentication from multiple places, but it does not merge them intelligently. If two different sources define credentials, the last-loaded one will override the others.

That can lead to confusing situations where authentication works locally but fails elsewhere.

Authentication depends on where Composer is running

One of the most common points of confusion is that Composer authentication isn’t a one-time setup.

Composer needs valid credentials everywhere it runs, including:

• your laptop
• a teammate’s machine
• GitHub Actions runners
• staging servers
• production deploy pipelines

That’s why the next sections focus on the same ACF PRO authentication mechanism, applied correctly across different environments.

The goal is to ensure ACF PRO installs behave consistently, no matter where Composer is executed.

Using auth.json for local development

For local environments, auth.json is the simplest and safest option.

Composer automatically loads this file if it exists, and it’s ignored by default in most .gitignore templates.

A minimal auth.json for ACF PRO looks like this:

{

  "http-basic": {

    "composer.advancedcustomfields.com": {

      "username": "YOUR_ACF_PRO_LICENSE_KEY",

      "password": ""

    }

  }

}

Why this works well locally

• Setup is fast and developer-friendly
  
• Credentials stay outside version control
  
• Composer automatically applies them during install/update
  
• Each developer can use their own license key if needed

This approach is especially useful for onboarding new developers. A project can include an auth.json.example file, and each developer creates their own local copy with their license key.

Common mistakes that trigger 401 errors

Even small issues will cause Composer authentication to fail:

• Using the wrong domain (e.g., advancedcustomfields.com)
  
• Adding whitespace or hidden characters in the license key
  
• Nesting the JSON incorrectly
  
• Accidentally committing auth.json and overwriting secrets elsewhere

After creating or updating auth.json, clear Composer’s cache:

composer clear-cache

Then retry the install or update.

Keeping credentials out of git with environment variables

While auth.json is ideal locally, file-based secrets don’t scale well to shared or automated environments.

For CI, staging, and production, Composer supports authentication via the COMPOSER_AUTH environment variable.

This variable accepts the same JSON structure as auth.json.

Example:

export COMPOSER_AUTH='{

  "http-basic": {

    "composer.advancedcustomfields.com": {

      "username": "YOUR_ACF_PRO_LICENSE_KEY",

      "password": ""

    }

  }

}'

Composer reads this automatically at runtime.

This also aligns with broader WordPress development best practices around security and deployment.

Why this prevents persistent 401 errors

Many ACF PRO authentication issues only appear outside local development because:

• auth.json exists locally but not on the server
  
• environment variables were never configured
  
• secrets were scoped incorrectly in CI or deploy tooling

If Composer works locally but fails remotely, missing COMPOSER_AUTH is the most likely cause.

Environment variables are also easier to rotate and manage securely, since they don’t require writing secrets to disk.

Authenticating ACF PRO in GitHub Actions

GitHub Actions does not inherit your local machine configuration.

Each runner starts clean, meaning:

• no auth.json
  
• no stored Composer credentials
  
• no interactive prompt
  

So Composer attempts to download ACF PRO and fails immediately with:

HTTP 401 Unauthorized

The correct approach is to store your license key as a GitHub Actions secret and inject it into Composer authentication before running installs.

Option 1: Generate auth.json in the workflow

- name: Authenticate Composer

  run: |

    echo '{

      "http-basic": {

        "composer.advancedcustomfields.com": {

          "username": "${{ secrets.ACF_PRO_KEY }}",

          "password": ""

        }

      }

    }' > auth.json

Option 2: Use COMPOSER_AUTH directly

env:

  COMPOSER_AUTH: >

    {"http-basic":{"composer.advancedcustomfields.com":{"username":"${{ secrets.ACF_PRO_KEY }}","password":""}}}

Both approaches are valid. The critical requirement is: Authentication must exist before Composer runs.

Without this, CI builds will fail unpredictably, especially when dependencies need updating.

Bedrock workflows and Composer authentication

Roots Bedrock doesn’t change how Composer authentication works — but it does make credential placement more visible because WordPress itself becomes a Composer dependency.

Best practice with Bedrock is:

• Use auth.json locally
  
• Use COMPOSER_AUTH for CI and deploy pipelines
  
• Never commit license keys into the repository

Modern WordPress builds often rely on Composer and structured tooling, and our guide on WordPress workflow offers a useful perspective on how teams streamline development.

Tooling note

If you’re using community tools like Log1x’s ACF Composer integration, it’s important to understand:

• These tools rely on Composer underneath
  
• ACF PRO 401 errors are still authentication failures
  
• This is not a Bedrock bug or plugin bug

If Composer cannot authenticate, no wrapper tool can fix that.

Trellis Vault and production deployments

In Trellis-based infrastructure, secrets should live in Vault — not in files committed to disk.

Store your ACF PRO license key as a Vault variable, then expose it as COMPOSER_AUTH during deployment.

This ensures:

• license keys never touch disk
  
• production and staging can use separate credentials
  
• deploys remain deterministic and non-interactive
  
• ACF PRO updates behave reliably in automated pipelines

If Trellis deploys fail with 401 while local installs succeed, Vault configuration is the first place to check.

Production environments are where authentication mistakes are most costly, so treating credentials as first-class secrets is essential.

Debugging persistent 401 errors

If you’ve added credentials and Composer still fails, run:

composer config --global --list

and:

composer diagnose

Then confirm:

• Is Composer reading the expected auth source?
  
• Are multiple auth sources overriding each other?
  
• Is the license key valid and active?
  
• Are credentials attached to the correct host?

Remember: the last-loaded auth source wins, which can lead to silent overrides and confusing failures. In many cases, the fastest fix is simply ensuring only one authentication source is active in the environment you’re debugging.

We also provide an official debugging resource that can help confirm whether errors are authentication-related or environment-related.

Real-world failure scenarios to watch for

Even when authentication looks correct, a few common edge cases can still trigger 401 errors.

Scenario 1: “It works locally but fails in CI”

This is by far the most common ACF PRO Composer issue.

Local installs succeed because your machine has auth.json, but your CI runner starts clean and has no credentials at all.

Fix: Ensure your pipeline injects COMPOSER_AUTH or generates auth.json before running composer install.

Scenario 2: Credentials are scoped to the wrong domain

Composer authentication is host-specific. If credentials are attached to:

advancedcustomfields.com

instead of:

composer.advancedcustomfields.com

Composer will still fail with a 401.

Fix: Double-check the exact domain in your auth configuration.

Scenario 3: A global Composer config overrides the project config

Sometimes developers have old credentials stored globally:

~/.composer/auth.json

Those can silently override the credentials in your project directory.

Fix: Inspect global config output and remove outdated entries if needed.

Scenario 4: Secrets are present but not actually available in the environment

In GitHub Actions or deploy pipelines, secrets can fail to load because:

• they were added under the wrong repository
  
• they are not available to forks
  
• they are not exposed to the correct branch or environment
  

Fix: Confirm the secret exists and is being passed into the job.

Scenario 5: The license key is inactive or expired

While most 401s are configuration-related, Composer will also fail if the license key is no longer valid.

Fix: Verify your ACF PRO license is active in your ACF account dashboard.

Scenario 6: Cached authentication is stale

Composer can cache credentials and repository metadata aggressively.

Fix: Clear cache and retry:

composer clear-cache

composer update --no-cache

Debugging becomes much easier once you treat ACF PRO authentication as an environment-level dependency, not just a local configuration detail.

ACF PRO Composer Authentication Checklist

To eliminate ACF PRO Composer 401 errors permanently, use this checklist to confirm every environment is configured correctly.

ACF PRO Composer authentication checklist

Before running Composer installs or updates, verify:

You are authenticating against the correct host:

composer.advancedcustomfields.com

• Your license key is used as the HTTP Basic Auth username
  
• The password field is left blank
  
• Credentials are never committed into composer.json
  
• auth.json is used only for local development and is gitignored
  
• CI pipelines inject authentication using COMPOSER_AUTH or generated auth.json
  
• GitHub Actions secrets are correctly scoped and available to the workflow
  
• Production deployments store keys in a secrets manager (Vault, environment vars, etc.)
  
• Only one active auth source exists per environment to avoid overrides
  
• Composer cache is cleared when troubleshooting persistent failures

Outcome

Once these pieces are in place, ACF PRO becomes a stable Composer dependency:

• installs work consistently
  
• updates run reliably
  
• CI builds stop failing unexpectedly
  
• production deploys remain secure and repeatable
  

Authentication stops being a recurring fire drill — and ACF PRO fits cleanly into modern WordPress delivery pipelines.

For additional background on how ACF PRO integrates into Composer-driven setups, the overview of Composer support for ACF PRO is your next best read.