Client Configuration and Authentication
Relevant source files
The following files were used as context for generating this wiki page:
Infrahub Python SDK uses a centralized configuration system and a dual-client architecture to manage interactions with the Infrahub API. It provides structured methods to define connection parameters, handle authentication via API keys, and manage request priorities and retry logic.
This system ensures that developers can interact with infrastructure data as native Python objects while maintaining consistent behavior across both asynchronous and synchronous execution paths.
Sources: dev/constitution.md:12-16, AGENTS.md:5-9
Configuration Management
The SDK manages settings through Pydantic v2 models, primarily defined in ConfigBase. This model defines the schema for connection details, authentication credentials, and operational behaviors like request retries and timeouts.
Core Configuration Fields
The configuration allows users to specify the target Infrahub instance and security credentials. It supports automatic binding to environment variables (e.g., INFRAHUB_PRIORITY).
| Field | Type | Description |
|---|---|---|
address | str | The URL of the Infrahub server. |
api_token | str | None | The token used for authenticating requests. |
priority | Priority | None | Default request priority (high, normal, low). |
rate_limit_retry_enabled | bool | Enables automatic retries on HTTP 429 responses. |
rate_limit_max_retries | int | Maximum number of retry attempts for rate limits. |
Sources: infrahub_sdk/config.py:1-10, dev/specs/ihs-259-sdk-x-priority-header/tasks.md:T004, dev/specs/ihs-249-sdk-429-retry/tasks.md:T003
Priority and Retries
The configuration includes specific enums for request handling. The Priority enum manages the X-Priority header, while the retry machinery handles backoff logic for rate-limited requests.
The diagram shows how ConfigBase settings influence authentication, headers, and request resiliency.
Sources: dev/specs/ihs-259-sdk-x-priority-header/tasks.md:T002-T004, dev/specs/ihs-249-sdk-429-retry/tasks.md:T005
Authentication and Headers
Authentication is handled by injecting the api_token into the request headers. The SDK primarily uses the X-INFRAHUB-KEY header for this purpose.
Header Injection Logic
Headers are initialized in BaseClient.__init__. The client merges global headers (like authentication and default priority) with per-request overrides.
- Authentication: If an API token is present in the configuration, it is added to
self.headers["X-INFRAHUB-KEY"]. - Priority: If a default priority is configured, it is added to
self.headers["X-Priority"]. - Tracking: Requests include an
X-Infrahub-Trackerheader for observability.
Sources: infrahub_sdk/client.py:217-218, dev/specs/ihs-259-sdk-x-priority-header/tasks.md:T005, T013
Client Architecture
The SDK enforces a "Dual API Parity" principle. Every public feature must exist on both the InfrahubClient (async) and InfrahubClientSync (sync) with matching signatures.
Client Hierarchy
Both client types inherit from BaseClient, which manages shared logic for configuration and header setup.
The class diagram represents the inheritance structure ensuring parity between async and sync implementations.
Sources: dev/constitution.md:18-24, infrahub_sdk/client.py:200-220
Initialization
Consumers should not instantiate InfrahubClient directly in specialized contexts like the CLI. Instead, they use initialize_client() to ensure proper configuration loading and standard error handling.
Sources: dev/constitution.md:43-45, AGENTS.md:28-32
Request Resilience (429 Retries)
The SDK implements a specialized handler for HTTP 429 (Too Many Requests) responses. This machinery is wired into GraphQL, multipart, and streaming transports.
- Exponential Backoff: Computes delays using
min(backoff_max, backoff_base * 2**attempt). - Retry-After Support: The SDK parses the
Retry-Afterheader (delta-seconds or HTTP-date) and respects server-directed wait times. - Jitter: Applies random jitter to delays to prevent thundering herd problems.
Sources: dev/specs/ihs-249-sdk-429-retry/tasks.md:T005, T007-T010
Summary
Client Configuration and Authentication in the Infrahub SDK provide a robust foundation for interacting with infrastructure APIs. By combining Pydantic-based configuration, a dual-client architecture for async/sync parity, and advanced request resilience features like jittered exponential backoff, the SDK ensures stable and secure programmatic access to Infrahub data.