ReqManagedAgents.Providers.ClaudeManagedAgents.Federation (ReqManagedAgents v0.17.0)

Copy Markdown View Source

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.

Summary

Types

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.

t()

: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.

Types

clock()

@type clock() :: integer() | (-> integer())

http()

@type http() :: %{
  optional(atom()) => term(),
  base_url: String.t(),
  req_options: keyword()
}

http_detail()

@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()

@type identity_token() :: (-> {:ok, String.t()} | {:error, term()})

reason()

@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()

@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.