Struct OAuth2ClientCredentials 

pub struct OAuth2ClientCredentials { /* private fields */ }

A TokenProvider implementing the OAuth 2.0 client credentials grant (RFC 6749 §4.4) with caching and proactive refresh.

• Tokens are cached until shortly before expiry (with_refresh_leeway, default 30 s before expires_in elapses, but never less than half the lifetime, so a short-lived token is still reused) and refreshed on demand.
• Concurrent callers needing a refresh collapse into a single token request (single-flight), and all of them get that request’s outcome — its failure as well as its success, so a dead endpoint costs every waiting caller one timeout, not one each in turn.
• A failed refresh is remembered for with_failure_backoff (default 1 s): callers in that window get the same error without a new request.
• A caller that is cancelled mid-refresh does not strand the others: the attempt is marked abandoned and the next waiter starts a new one.
• The client secret is never logged, never echoed in errors, and redacted from Debug output.

Built on the crate’s own HTTP stack — no additional OAuth dependencies. With the default tls-rustls feature the token endpoint may be https:// (the norm); without it, only http:// endpoints are reachable and an https:// endpoint fails at construction with an actionable error.

Implementations

impl OAuth2ClientCredentials

pub fn new( token_url: impl Into<String>, client_id: impl Into<String>, client_secret: impl Into<String>, ) -> OAuth2ClientCredentials

Creates a provider for the given token endpoint and client credentials.

pub fn from_agent_card( card: &AgentCard, scheme_name: &str, client_id: impl Into<String>, client_secret: impl Into<String>, ) -> Result<OAuth2ClientCredentials, ClientError>

Reads the token endpoint from an agent card’s OAuth 2.0 client-credentials flow.

scheme_name is the key in the card’s securitySchemes map. Request scopes with with_scopes — the card’s flow lists the scopes the agent offers (with descriptions); which of them to request is your decision.

Errors

Returns ClientError::InvalidEndpoint when the scheme is missing, is not an OAuth 2.0 scheme, or has no client-credentials flow.

pub async fn from_oidc_issuer( issuer: &str, client_id: impl Into<String>, client_secret: impl Into<String>, ) -> Result<OAuth2ClientCredentials, ClientError>

Discovers the token endpoint from an OIDC issuer (RFC 8414 / OIDC Discovery: {issuer}/.well-known/openid-configuration) and creates a provider for it.

Errors

Returns a ClientError when the discovery document cannot be fetched or has no token_endpoint.

pub fn with_scopes<I, S>(self, scopes: I) -> OAuth2ClientCredentials

where I: IntoIterator<Item = S>, S: Into<String>,

Sets the scopes to request (joined with spaces per RFC 6749 §3.3).

pub fn with_audience( self, audience: impl Into<String>, ) -> OAuth2ClientCredentials

Sets the audience parameter (used by some authorization servers, e.g. Auth0, to select the target API).

pub fn with_extra_param( self, key: impl Into<String>, value: impl Into<String>, ) -> OAuth2ClientCredentials

Adds an extra form parameter to the token request.

pub const fn with_auth_style( self, style: TokenEndpointAuthStyle, ) -> OAuth2ClientCredentials

Sets how client credentials are presented (default: TokenEndpointAuthStyle::Basic).

pub const fn with_refresh_leeway( self, leeway: Duration, ) -> OAuth2ClientCredentials

Sets how long before expiry a cached token is refreshed (default 30 s).

Capped at half the token’s lifetime: a token that lives 20 s is cached for 10 s rather than not at all.

pub const fn with_request_timeout( self, timeout: Duration, ) -> OAuth2ClientCredentials

Sets the token-request timeout (default 30 s).

pub const fn with_failure_backoff( self, backoff: Duration, ) -> OAuth2ClientCredentials

Sets how long a failed refresh is remembered (default 1 s).

Callers arriving within this window after a failure get the same error immediately instead of a new token request. Duration::ZERO turns the negative cache off; callers already waiting on an attempt share its outcome either way.

Trait Implementations

impl Debug for OAuth2ClientCredentials

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl TokenProvider for OAuth2ClientCredentials

fn access_token( &self, ) -> Pin<Box<dyn Future<Output = Result<String, ClientError>> + Send + '_>>

Returns a currently-valid access token.

fn invalidate(&self, token: &str)

Tells the provider the agent rejected token (HTTP 401), so it should not hand that token out again.