Sycophant.Auth behaviour (sycophant v0.4.2)

Copy Markdown

Behaviour and registry for provider authentication strategies.

Each provider implements this behaviour to produce Tesla middleware entries for its authentication scheme. The pipeline dispatches through Sycophant.Registry, so adding a new provider never requires editing the pipeline.

Built-in Strategies

Unregistered providers fall back to the Bearer strategy.

Optional callbacks

  • path_params/1 - returns provider-specific URL path parameters
  • prepare_credentials/1 - mutates the credential map before transport assembly. Used by providers that need to perform side-effecting work (token exchange, signing nonce, etc.) and surface results back into the credentials map (e.g. :base_url, :copilot_token).

Summary

Callbacks

middlewares(credentials)
path_params(credentials)
prepare_credentials(credentials)

Functions

middlewares_for(provider, credentials)

Returns the list of Tesla middlewares needed to authenticate requests for the given provider. Looks up the provider in Sycophant.Registry and delegates to its middlewares/1 callback. Falls back to a generic Bearer token strategy for unregistered providers.

path_params_for(provider, credentials)

Returns provider-specific path parameters derived from the given credentials.

prepare_credentials_for(provider, credentials)

Optionally mutates credentials before transport assembly.

Callbacks

middlewares(credentials)

@callback middlewares(credentials :: map()) :: [Tesla.Client.middleware()]

path_params(credentials)

(optional) 
@callback path_params(credentials :: map()) :: keyword()

prepare_credentials(credentials)

(optional) 
@callback prepare_credentials(credentials :: map()) ::
  {:ok, map()} | {:error, Splode.Error.t()}

Functions

middlewares_for(provider, credentials)

@spec middlewares_for(atom(), map()) :: [Tesla.Client.middleware()]

Returns the list of Tesla middlewares needed to authenticate requests for the given provider. Looks up the provider in Sycophant.Registry and delegates to its middlewares/1 callback. Falls back to a generic Bearer token strategy for unregistered providers.

path_params_for(provider, credentials)

@spec path_params_for(atom(), map()) :: keyword()

Returns provider-specific path parameters derived from the given credentials.

Some providers (e.g. Bedrock) require dynamic URL segments such as region or model ID. If the provider module implements the optional path_params/1 callback, those parameters are returned; otherwise an empty list is returned.

prepare_credentials_for(provider, credentials)

@spec prepare_credentials_for(atom(), map()) ::
  {:ok, map()} | {:error, Splode.Error.t()}

Optionally mutates credentials before transport assembly.

Providers that need side-effecting work (e.g. token exchange) implement prepare_credentials/1 to populate fields like :base_url or session tokens into the credentials map. The pipeline calls this between Credentials.resolve/2 and transport_opts/3, so any :base_url or auth-relevant field set here flows naturally into the upstream Tesla middleware stack.

Returns {:ok, credentials} unchanged for providers without an implementation.