description: Configure bearer tokens, basic authentication, and request headers.

Authentication

Authentication can be applied to one request or configured on a handler. withToken() sets a bearer Authorization header; withAuth() configures Guzzle basic authentication.

Bearer token

$handler = fetch_client()->getHandler();
$response = $handler
    ->withToken($token)
    ->get('https://api.example.test/v1/profile');

For a single call, pass a token request option to fetch() or a verb helper. Helper options are per-request.

$response = fetch('https://api.example.test/v1/profile', ['token' => $token]);

For an API key or custom scheme, set a request header:

$response = get('https://api.example.test/v1/items', null, [
    'headers' => ['X-API-Key' => $apiKey],
]);

Basic authentication

$response = fetch('https://api.example.test/v1/private', [
    'auth' => [$username, $password],
]);

Use HTTPS and obtain credentials from an appropriate secret store. Do not write tokens or passwords to logs, fixtures, or committed examples. The offline fixture is checked by composer docs:examples.

<?php

declare(strict_types=1);

require dirname(__DIR__, 3).'/vendor/autoload.php';

use Fetch\Interfaces\Response as FetchResponse;
use Fetch\Testing\MockResponse;
use Fetch\Testing\MockServer;

MockServer::fake([
    'GET https://api.example.test/v1/profile' => MockResponse::json([
        'id' => 7,
    ]),
]);
MockServer::preventStrayRequests();

$handler = fetch_client(reset: true)->getHandler();
$handler->withToken('example-token');
$response = $handler->get('https://api.example.test/v1/profile');

if (! ($response instanceof FetchResponse) || $response->json()['id'] !== 7) {
    throw new RuntimeException('The authenticated request example failed.');
}

MockServer::assertSent(
    static fn ($request): bool => $request->hasHeader('Authorization') &&
        $request->getHeaderLine('Authorization') === 'Bearer example-token',
);