Headers and Authentication

This document explains how to set HTTP headers and configure authentication for API requests. It covers header management methods available on the ApiRequest class, authentication token handling, and common header convenience methods.

For information about configuring request bodies and content serialization, see Request Body and Serialization. For general request configuration including URLs and parameters, see Request Configuration.

Overview

The API client provides a fluent interface for managing HTTP headers through the ApiRequest class. All header operations are immutable, returning new instances with the modified headers applied to the underlying PSR-7 request object.

Sources: src/ApiRequest.php1-241

Header Management Architecture

Headers in the API client are managed through a wrapper pattern that delegates to the underlying PSR-7 request interface. The ApiRequest class maintains an internal RequestInterface instance and provides convenient methods that modify this instance immutably.

Sources: src/ApiRequest.php12-14 src/ApiRequest.php46-63 src/ApiRequest.php217-224

Setting Headers

Basic Header Methods

The ApiRequest class provides two primary methods for setting headers:

Method	Parameters	Description
withHeader()	string $key, string $value	Sets a single header, replacing any existing value
withHeaders()	array $headers	Sets multiple headers from an associative array

Both methods replace existing header values. The withHeader() method internally calls withHeaders() with a single-element array.

Sources: src/ApiRequest.php46-63

Adding Headers Without Replacement

For cases where you need to add header values without replacing existing ones (useful for headers that support multiple values), use the additive header methods:

Method	Parameters	Description
withAddedHeader()	string $key, string $value	Adds a header value without removing existing values
withAddedHeaders()	array $headers	Adds multiple header values

These methods are particularly useful for headers like Accept, Cache-Control, or custom headers that may have multiple values.

Sources: src/ApiRequest.php140-157

Removing Headers

Headers can be removed using the following methods:

Method	Parameters	Description
withoutHeader()	string $header	Removes a single header
withoutHeaders()	array $headers	Removes multiple headers

Sources: src/ApiRequest.php160-177

Authentication

Token-Based Authentication

The withToken() method provides a convenient way to add authorization tokens to requests. It automatically formats the Authorization header according to the specified token type.

Parameter	Type	Default	Description
$token	string	required	The authentication token
$type	string	'Bearer'	The token type (e.g., 'Bearer', 'Token', 'Basic')

The method constructs the Authorization header by concatenating the type and token with a space, then trimming any extra whitespace.

Sources: src/ApiRequest.php124-129

Common Authentication Patterns

The following table shows common authentication patterns and how to implement them:

Authentication Type	Implementation Example	Resulting Header
Bearer Token	withToken('abc123')	Authorization: Bearer abc123
API Key (Bearer)	withToken('key_123456')	Authorization: Bearer key_123456
Token Auth	withToken('xyz789', 'Token')	Authorization: Token xyz789
Custom Type	withToken('secret', 'ApiKey')	Authorization: ApiKey secret
Direct Header	withHeader('Authorization', 'Custom xyz')	Authorization: Custom xyz
API Key Header	withHeader('X-API-Key', 'key123')	X-API-Key: key123

Common Header Shortcuts

The ApiRequest class provides convenience methods for commonly used headers:

Content-Type Headers

Method	Sets	Value
contentType()	Content-Type	Custom value
asJson()	Content-Type	application/json
asForm()	Content-Type	application/x-www-form-urlencoded

Note: The asJson() and asForm() methods also manage the dataChanged flag and trigger body format conversion when switching between content types.

Sources: src/ApiRequest.php66-105

Accept Headers

Method	Sets	Value
accept()	Accept	Custom value
acceptJson()	Accept	application/json

These methods indicate the content type that should be returned by the server.

Sources: src/ApiRequest.php107-121

User-Agent Header

The withUserAgent() method sets the User-Agent header:

The method accepts either a boolean or string, trims the value, and sets it as the User-Agent header. This is useful for identifying your application to the API server.

Sources: src/ApiRequest.php133-137

Header Method Reference

The following diagram shows all header-related methods and their relationships:

Sources: src/ApiRequest.php46-177

Header Persistence Through Request Lifecycle

Headers set on an ApiRequest instance persist through the entire request lifecycle, including middleware processing and HTTP execution. The following diagram illustrates this flow:

Sources: src/ApiRequest.php217-224

Integration with Request Building

Headers are typically set during the request building phase in the PendingRequest orchestration. The fluent interface allows chaining header methods with other request configuration:

The immutable nature of header methods ensures that each step in the chain produces a new ApiRequest instance with the accumulated configuration, maintaining thread safety and preventing unintended side effects.

Sources: src/ApiRequest.php46-137