The Authentication component allows you to to implement authentication methods which can simply update the request with authentication detail (for example by adding an Authorization header). This is useful when you have to send multiple requests to the same endpoint. Using an authentication implementation, these details can be separated from the actual requests.


$ composer require php-http/message

Authentication Methods

Method Parameters Behavior
Basic Auth Username and password Authorization header of the HTTP specification
Bearer Token Authorization header of the HTTP specification
WSSE Username and password Authorization header of the HTTP specification
Query Params Array of param-value pairs URI parameters
Chain Array of authentication instances Behaviors of the underlying authentication methods
Matching An authentication instance and a matcher callback Behavior of the underlying authentication method if the matcher callback passes

Integration with HTTPlug

Normally requests must be authenticated “by hand” which is not really convenient.

If you use HTTPlug, you can integrate this component into the client using the authentication plugin.


General usage looks like the following:

$authentication = new AuthenticationMethod();

/** @var Psr\Http\Message\RequestInterface */

Basic Auth

use Http\Message\Authentication\BasicAuth;

$authentication = new BasicAuth('username', 'password');


use Http\Message\Authentication\Bearer;

$authentication = new Bearer('token');


use Http\Message\Authentication\Wsse;

$authentication = new Wsse('username', 'password');

Query Params

use Http\Message\Authentication\QueryParam;

$authentication = new QueryParam([
    'access_token' => '9zh987g86fg87gh978hg9g79',


Using query parameters for authentication is not safe. Only use it when this is the only authentication method offered by a third party application.


The idea behind this authentication method is that in some cases you might need to authenticate the request with multiple methods.

For example it’s a common practice to protect development APIs with Basic Auth and the regular token authentication as well to protect the API from unnecessary processing:

use Http\Message\Authentication\Chain;

$authenticationChain = [
    new AuthenticationMethod1(),
    new AuthenticationMethod2(),

$authentication = new Chain($authenticationChain);


With this authentication method you can conditionally add authentication details to your request by passing a callable to it. When a request is passed, the callable is called and used as a boolean value in order to decide whether the request should be authenticated or not. It also accepts an authentication method instance which does the actual authentication when the condition is fulfilled.

For example a common use case is to authenticate requests sent to certain paths:

use Http\Message\Authentication\Matching;
use Psr\Http\Message\RequestInterface;

$authentication = new Matching(
    new AuthenticationMethod1(),
    function (RequestInterface $request) {
        $path = $request->getUri()->getPath();

        return 0 === strpos($path, '/api');

In order to ease creating matchers for URLs/paths, there is a static factory method for this purpose: createUrlMatcher The first argument is an authentication method, the second is a regular expression to match against the URL:

use Http\Message\Authentication\Matching;

$authentication = Matching::createUrlMatcher(new AuthenticationMethod(), '\/api');

Implement Your Own

Implementing an authentication method is easy: only one method needs to be implemented:

use Http\Message\Authentication;
use Psr\Http\Message\RequestInterface;

class MyAuth implements Authentication
    public function authenticate(RequestInterface $request)
        // do something with the request

        // keep in mind that the request is immutable - return the updated
        // version of the request with the authentication information added
        // to it.
        return $request;