Skip to content

HTTP Basic Authentication with Guzzle in PHP

Guzzle accepts HTTP basic authentication through an auth array holding a username and password.

OUTPUT FORMATSHTMLJSONMarkdown

The main choice is scope: configure it once on the client for all of its requests, or supply it on individual requests when credentials are needed only sometimes.

Decide where the credentials belong

Choose client-level auth when a dedicated client will only talk to one authenticated service. That keeps each call shorter and prevents accidentally omitting credentials. Choose per-request auth when the same client also makes public calls or when different endpoints need different credentials. In both cases the value is a two-item array: username first, password second.

Apply auth to every request from one client

Pass auth while constructing the client. Every request issued through that instance then includes the credentials automatically. The worked example sends a GET request to a basic-auth test endpoint, reads the response body, and prints the status code followed by the body. A successful run shows status 200 with authenticated true in the returned data.

Apply auth only to selected requests

Create the client without auth, then include auth in the options for the specific call. This is the better fit for mixed public and private endpoints. The example uses the same test endpoint and prints the same status and body, confirming that the per-request form reaches the server with credentials even though the client itself has none configured.

Keep session state across calls

Per-request credentials alone do not create a persistent session. When a sequence of calls should share session state without repeating credentials, enable cookie persistence when the client is created. That setting is separate from auth: auth proves identity on each request, while cookies carry session state between requests.

Avoid two common failures

A rejected login returns 401. Without exception handling around RequestException or its ClientException subclass, that failure throws and halts execution, leaving no chance to inspect the response. Wrap authenticated calls when you need to log, retry, or branch on failure. Also remember that basic auth is only base64 encoding, not encryption, so credentials must travel over HTTPS rather than plain HTTP.

Quick check before you run it

Before sending a request, confirm three things: the auth array contains the correct username and password in that order, the chosen scope matches the endpoint, and the URL uses HTTPS. After sending, check for a 200 response and authenticated true on the test endpoint, or handle a 401 through the exception path instead of letting it terminate the script.

Client-level versus per-request auth
ScopeBest fitTrade-off
Client constructorAll requests from that client need the same credentialsShorter calls, but credentials apply even to public endpoints used through that client
Per-request optionOnly some calls need credentials, or credentials differ by callMore explicit control, but each protected call must include auth

Scope choice only; both forms use the same username and password array.

Frequently asked questions

Where do I put the credentials in Guzzle?

Place the username and password in an auth array. Put it in the Client constructor when every request from that client should carry credentials, or pass it as a request option when only selected calls need them.

How do I keep a session when using per-request auth?

Use the per-request form for those calls. If the login should survive across several requests without repeating the credentials each time, enable cookie persistence on the Client.

Why does a failed login stop my script?

Wrap the call so a RequestException, including its ClientException subclass, can be caught and the response inspected instead of letting the script stop.

Is HTTP basic auth encrypted?

Basic auth only base64-encodes the credentials; it does not encrypt them. Send them only over HTTPS.