# How DS2API Uses the X-Ds2-Target-Account Header for Account Pinning

> Learn how the DS2API X-Ds2-Target-Account header lets clients select specific managed accounts, bypassing default assignments for precise control. Understand account pinning.

- Repository: [CJACK./ds2api](https://github.com/CJackHwang/ds2api)
- Tags: internals
- Published: 2026-04-26

---

**The `X-Ds2-Target-Account` header allows API clients to explicitly select a specific managed account from the DS2API pool, overriding the default automatic assignment behavior.**

The `CJackHwang/ds2api` repository implements the `X-Ds2-Target-Account` header as a request-scoped override mechanism for account selection. This header bridges the gap between client intent and server-side resource allocation, enabling precise routing to specific managed accounts defined in the server configuration.

## Header Extraction in the Auth Resolver

When DS2API receives a request, the authentication resolver immediately extracts the target account identifier from the incoming headers. In [`internal/auth/request.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/auth/request.go) (lines 72–78), the `Determine` method retrieves and sanitizes the header value:

```go
target := strings.TrimSpace(req.Header.Get("X-Ds2-Target-Account"))

```

The trimmed `target` string is then passed to `acquireManagedRequestAuth`, which initiates the account binding process. If the header is absent or contains only whitespace, the resolver treats the request as having no preference, triggering the default pool selection behavior.

## Account Pool Selection Logic

The account pool in [`internal/account/pool_acquire.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/account/pool_acquire.go) (lines 15–33) handles the actual resource allocation through the `AcquireWait` method. This method implements a priority-based selection algorithm:

- **Explicit targeting**: When `target` contains a valid account identifier, `AcquireWait` attempts to acquire that specific resource exclusively via `acquireLocked`.
- **Fallback behavior**: If the requested account is unavailable or the target string is empty, the pool falls back to selecting any free managed account from the available set.

```go
// Acquire a specific target, waiting if necessary
acc, ok := p.AcquireWait(ctx, target, tried)

```

The pool maintains thread safety through its internal locking mechanisms, ensuring that the `X-Ds2-Target-Account` header respects concurrent request boundaries and prevents double-allocation of single-use accounts.

## CORS Configuration for Cross-Origin Requests

DS2API explicitly whitelists the custom header in its CORS middleware to support browser-based clients. The `defaultCORSAllowHeaders` slice in [`internal/server/router.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/server/router.go) (lines 157–162) includes the header among standard authorization fields:

```go
var defaultCORSAllowHeaders = []string{
    "Content-Type",
    "Authorization",
    "X-API-Key",
    "X-Ds2-Target-Account",
    // …
}

```

This configuration ensures that preflight `OPTIONS` requests succeed when web applications attempt to send the targeting header across origins.

## Testing and Validation

The repository includes comprehensive test coverage for header-based account selection. In [`internal/auth/auth_edge_test.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/auth/auth_edge_test.go) (line 387), unit tests verify that setting the header forces the resolver to bind to the requested account:

```go
req.Header.Set("X-Ds2-Target-Account", "acc2@test.com")

```

These tests validate both the happy path (successful targeting) and edge cases (invalid identifiers, missing headers, and concurrent access scenarios).

## Client Implementation Example

To utilize the header in production requests, clients include it alongside authentication credentials:

```bash
curl -H "X-API-Key: <your-api-key>" \
     -H "X-Ds2-Target-Account: acc2@example.com" \
     https://api.ds2.example.com/v1/chat/completions

```

## Summary

- **The `X-Ds2-Target-Account` header** enables request-level pinning to specific managed accounts in DS2API.
- **Extraction occurs** in [`internal/auth/request.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/auth/request.go), where the resolver sanitizes the header value before passing it to the account pool.
- **Selection logic** in [`internal/account/pool_acquire.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/account/pool_acquire.go) prioritizes explicit targets through `AcquireWait`, falling back to automatic selection when necessary.
- **Browser compatibility** is guaranteed by CORS configuration in [`internal/server/router.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/server/router.go) that explicitly allows the custom header.
- **Behavioral contracts** are enforced by unit tests in [`internal/auth/auth_edge_test.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/auth/auth_edge_test.go) verifying correct account binding and error handling.

## Frequently Asked Questions

### What happens if the requested account in the X-Ds2-Target-Account header is already in use?

According to the pool implementation in [`internal/account/pool_acquire.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/account/pool_acquire.go), the `AcquireWait` method either waits for the account to become available or falls back to the next free account if the target cannot be immediately acquired. The exact behavior depends on the pool's current state and the `exclude` map passed to the acquisition function.

### Is the X-Ds2-Target-Account header case-sensitive?

The header follows standard HTTP conventions where the header name itself is case-insensitive per RFC 7230, but the account identifier value extracted in [`internal/auth/request.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/auth/request.go) is used exactly as provided (after `strings.TrimSpace` processing). Account matching against the pool depends on the exact string value configured in the server's account registry.

### Do I need to include the X-Ds2-Target-Account header in every request?

No. As implemented in [`internal/auth/request.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/auth/request.go), the header is optional. When omitted or empty, DS2API automatically selects any available managed account from the pool, functioning as a load-balanced proxy rather than a targeted one.

### How does DS2API prevent unauthorized account access via this header?

The resolver validates the requested account against the configured pool in [`internal/account/pool_acquire.go`](https://github.com/CJackHwang/ds2api/blob/main/internal/account/pool_acquire.go). If the identifier does not match a valid managed account, the `acquireLocked` check fails, and the system either selects a fallback account or returns an authentication error, preventing access to undefined or restricted resources.