# `ReqManagedAgents.Providers.ClaudeManagedAgents.Federation`
[🔗](https://github.com/cash-mckeeman/req_managed_agents/blob/v0.17.0/req_managed_agents/lib/req_managed_agents/providers/claude_managed_agents/federation.ex#L1)

Anthropic workload identity federation settings for a Claude Managed Agents
client, and the access-token cache behind them. Build a client with
`ReqManagedAgents.Providers.ClaudeManagedAgents.Client.new/1`; this module is
its `:federation` field.

Identity tokens carry a `jti` and are single use, so every exchange obtains a
new one and only one exchange per credential runs at a time. Only the caller
that performs a refresh waits for it. Every other caller holding a usable cached
token is served it at once, while another process refreshes and during the retry
pause after a failed refresh. A caller with no usable token waits at most
`:exchange_timeout`. For an access token expiring at `e`:

  * before `e - 120 s` the cached token is served;
  * from `e - 120 s` to `e - 30 s` one caller exchanges and the others keep
    the cached token; if the exchange fails the cached token keeps serving
    while retries pause for 10 seconds;
  * from `e - 30 s` the cached token is unusable: exchange or fail.

The 120 s and 30 s margins shrink to half and a quarter of the token's
lifetime when that is shorter (a 60 s token refreshes from 30 s before expiry).

The identity-token function is given `:identity_token_timeout` (10 s), and the
exchange request `:exchange_connect_timeout` (5 s) and `:exchange_receive_timeout`
(10 s); none uses the client's `:receive_timeout`. One refresh therefore takes at
most about 25 s, and the `:exchange_timeout` default (30 s) covers it, so a
waiter outlasts a holder that succeeds. When raising one of the three timeouts,
raise `:exchange_timeout` to at least their sum.

Tokens are cached per node, keyed by the settings and the identity-token
source (the file path, the function, or `:cache_key` when given). Each new
key is a separate exchange that spends a single-use identity token. Entries
whose token has expired are dropped whenever a new entry is written.

# `clock`

```elixir
@type clock() :: integer() | (-&gt; integer())
```

# `http`

```elixir
@type http() :: %{
  optional(atom()) =&gt; term(),
  base_url: String.t(),
  req_options: keyword()
}
```

# `http_detail`

```elixir
@type http_detail() :: %{status: integer() | nil, request_id: String.t() | nil}
```

What is known of a failed exchange's response: the HTTP status (`nil` when there was
no response) and Anthropic's `request-id` header, never the body.

# `identity_token`

```elixir
@type identity_token() :: (-&gt; {:ok, String.t()} | {:error, term()})
```

# `reason`

```elixir
@type reason() ::
  :identity_token_unreadable
  | :identity_token_invalid
  | :identity_token_unavailable
  | :identity_token_timeout
  | :exchange_timeout
  | {:exchange_rejected | :exchange_failed | :exchange_invalid_response,
     http_detail()}
```

# `t`

```elixir
@type t() :: %ReqManagedAgents.Providers.ClaudeManagedAgents.Federation{
  cache_key: term(),
  connect_timeout: pos_integer(),
  exchange_timeout: pos_integer(),
  identity_token: identity_token() | nil,
  identity_token_file: String.t() | nil,
  identity_token_timeout: pos_integer(),
  organization_id: String.t(),
  receive_timeout: pos_integer(),
  rule_id: String.t(),
  service_account_id: String.t() | nil,
  workspace_id: String.t() | nil
}
```

`:cache_key` is any term; clients sharing it, and the other settings, share one
cached access token even when each passes its own `:identity_token` closure.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
