# How the Tesla API Client is Configured in the HTTP Module in TeslaMate

> Discover how the Tesla API client is configured in the HTTP module. Learn about Finch pool architecture, environment settings, TLS, and proxy details for efficient traffic management.

- Repository: [TeslaMate/teslamate](https://github.com/teslamate-org/teslamate)
- Tags: internals
- Published: 2026-06-16

---

**The TeslaMate HTTP module configures the Tesla API client using a Finch-based connection pool architecture that isolates traffic by external service domain, with environment-driven settings for hosts, pool sizes, TLS versions, and proxy configurations.**

The `teslamate-org/teslamate` repository centralizes all external HTTP communication through the `TeslaMate.HTTP` module, which implements a robust Finch client configuration for the Tesla API and related services. Understanding how the Tesla API client is configured in the HTTP module reveals a sophisticated pool-per-service architecture that ensures reliable, high-concurrency connectivity with Tesla's owner API, authentication endpoints, and third-party services like Nominatim.

## Architecture of the TeslaMate HTTP Module

The module acts as a centralized **Finch** supervisor, defining discrete connection pools for each external domain to prevent cross-service contention and enable tailored connection parameters per endpoint.

### Service Isolation via Connection Pools

In [`lib/teslamate/http.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/http.ex) (lines 12-27), the `pools/0` function returns a map where keys represent base URLs and values specify pool configurations as keyword lists. This design creates separate connection pools for:

- The **Tesla API** host (`owner-api.teslamotors.com`)
- The **Tesla auth** endpoint (`auth.tesla.com`)
- The **Nominatim** reverse-geocoder
- **GitHub** API endpoints
- A fallback **default** pool for unspecified requests

Each pool maintains independent connection limits and protocol options, ensuring that heavy API usage against Tesla's servers does not exhaust connections available for geocoding or authentication workflows.

### Default Pool Configuration

The default pool uses the `:default` key with a size configurable via the `HTTP_POOL_SIZE` environment variable (defaulting to **5**), ensuring baseline connectivity for generic external requests that do not match specific service domains.

## Environment-Based Tesla API Configuration

The module leverages environment variables to dynamically configure Tesla-specific endpoints without requiring code changes or redeployment.

### Tesla API Host and Connection Limits

The Tesla API pool key derives from `TESLA_API_HOST` (defaulting to `https://owner-api.teslamotors.com`), with concurrent connection limits controlled by `TESLA_API_POOL_SIZE` (default **10**). This configuration resides at lines 13-15 of [`lib/teslamate/http.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/http.ex), allowing operators to point TeslaMate at different API environments or regional endpoints.

### Authentication Host TLS Configuration

The authentication endpoint uses `TESLA_AUTH_HOST` (default `https://auth.tesla.com`) and enforces specific security constraints: the pool forces both **HTTP/1 and HTTP/2** protocols and pins **TLS 1.3** through the `conn_opts` keyword list (lines 18-25). This strict TLS configuration ensures compatibility with Tesla's modern authentication infrastructure while maintaining connection reliability.

## Proxy Support and Network Options

Enterprise and privacy-conscious deployments can route traffic through HTTP proxies using standardized environment variable patterns.

### Dynamic Proxy Configuration

The `build_proxy_opts_from_env/1` function (lines 32-73) reads service-specific proxy variables such as `NOMINATIM_PROXY` or `TESLA_API_PROXY`, validates the URL format (requiring `http://host:port` schema), and returns `{:ok, [conn_opts: [proxy: …]]}` tuples that merge into the appropriate pool configuration. Invalid proxy URLs raise clear error messages during application startup, preventing silent connection failures.

## Request Interface and Finch Integration

The module exposes a clean, synchronous API for HTTP operations while abstracting the underlying pool selection logic from calling code.

### Supervisor Registration

The `child_spec/1` function (lines 75-77) registers `TeslaMate.HTTP` as a Finch supervisor within the OTP application tree, supplying the pool map generated by `pools/0` to the Finch process. This registration ensures that all configured pools start atomically with the application and remain available for the lifecycle of the node.

### Convenience Request Functions

The `get/2` and `post/3` functions (lines 79-97) wrap `Finch.build/4` and `Finch.request/3`, automatically injecting the module attribute `@pool_timeout` (**10,000 milliseconds**). These functions handle pool selection transparently based on the request URL's host, routing Tesla API calls to the high-capacity Tesla pool while directing Nominatim requests to the geocoding-specific pool.

```elixir

# Simple GET request to the Tesla API

TeslaMate.HTTP.get(
  "#{System.get_env("TESLA_API_HOST", "https://owner-api.teslamotors.com")}/api/1/vehicles",
  headers: [{"Authorization", "Bearer #{access_token}"}]
)

# POST request with a JSON body to the auth endpoint

payload = Jason.encode!(%{command: "START_CHARGE"})
TeslaMate.HTTP.post(
  "#{System.get_env("TESLA_AUTH_HOST", "https://auth.tesla.com")}/oauth2/v3/token",
  payload,
  headers: [{"Content-Type", "application/json"}]
)

# Nominatim request automatically uses the Nominatim pool

# (respects NOMINATIM_PROXY if configured)

TeslaMate.HTTP.get("https://nominatim.openstreetmap.org/reverse?format=json&lat=…&lon=…")

```

All calls through these functions inherit the configured timeout and automatically apply any proxy settings defined for the target service's connection pool.

## Summary

- **Finch-based architecture**: The Tesla API client is not a separate library but a configured instance of the Finch HTTP client managed by `TeslaMate.HTTP`.
- **Pool-per-service isolation**: Separate connection pools for Tesla API, auth, Nominatim, and GitHub prevent resource contention and enable service-specific tuning.
- **Environment-driven configuration**: Hosts, pool sizes (`TESLA_API_POOL_SIZE`, `HTTP_POOL_SIZE`), and timeouts are configurable via environment variables without code changes.
- **Enterprise proxy support**: The `build_proxy_opts_from_env/1` function enables HTTP proxy configuration per service using `<SERVICE>_PROXY` environment variables.
- **Synchronous convenience API**: The `get/2` and `post/3` functions provide a 10-second timeout default and automatic pool selection based on request URL.

## Frequently Asked Questions

### What HTTP client library does TeslaMate use for the Tesla API?

TeslaMate uses **Finch**, a high-performance HTTP client for Elixir built on Mint. According to the source code in [`lib/teslamate/http.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/http.ex), the `TeslaMate.HTTP` module configures Finch with multiple connection pools rather than using a separate Tesla API client library. All Tesla API wrappers in `lib/tesla_api/*.ex` ultimately delegate to this module.

### How do I configure a proxy for Tesla API requests in TeslaMate?

Set the appropriate environment variable (e.g., `TESLA_API_PROXY` or `NOMINATIM_PROXY`) to a valid `http://host:port` URL. The `build_proxy_opts_from_env/1` function validates the URL format at runtime and merges proxy options into the respective connection pool configuration during application startup.

### What is the default connection pool size for the Tesla API?

The default pool size is **10 concurrent connections**, configurable via the `TESLA_API_POOL_SIZE` environment variable. The default request timeout for all HTTP operations through the module is **10,000 milliseconds** (10 seconds), defined by the `@pool_timeout` module attribute.

### Why does TeslaMate use separate connection pools for different services?

Separate pools prevent **head-of-line blocking** between services and allow service-specific optimizations. For example, the Tesla auth pool forces **TLS 1.3** and specific HTTP protocol versions (lines 18-25), while the Nominatim pool might operate through a corporate proxy via `NOMINATIM_PROXY`. This isolation ensures that slow responses or connection limits on one service do not degrade performance for others.