​
Overview

When working with OAuth2 APIs, you’ll need to handle cases where credentials are either missing or have expired. Wildcard provides built-in mechanisms to handle these scenarios gracefully.

​
Types of Authentication Errors

There are two main types of authentication errors you might encounter:
  1. Missing Credentials (AuthRequiredError): Occurs when no authentication configuration exists for an API.
  2. Expired/Invalid Credentials (OAuthCredentialsRequiredException): Occurs when OAuth credentials are expired or invalid.

​
Handling Missing Credentials

When no authentication configuration exists for an API, you’ll receive an AuthRequiredError
Common Pitfall: You need to have called register_api_auth before running the tool.
from wildcard_core.auth.auth_helper import AuthRequiredError

try:
    response = await wildcard_client.run_tool_with_args(tool_name, **args)
except AuthRequiredError as e:
    # No authentication configuration exists
    print(f"Authentication required: {e.message}")

​
Handling Expired Credentials

When OAuth credentials are expired or invalid, you’ll receive an OAuthCredentialsRequiredException containing information needed to refresh the token 
from wildcard_core.auth.oauth_helper import OAuthCredentialsRequiredException

try:
    response = await wildcard_client.run_tool_with_args(tool_name, **args)
except OAuthCredentialsRequiredException as e:
    # Get OAuth info from the exception
    oauth_info = e.oauth_info
    resume_info = e.resume_info

    # Refresh the token
    await wildcard_client.refresh_token(
        api_service=oauth_info.api_service,
        webhook_url="your_webhook_url"
    )

    # Resume the original tool execution
    response = await wildcard_client.resume_tool(resume_info)

​
Understanding the Exception Data

The OAuthCredentialsRequiredException contains two important pieces of information:
  1. oauth_info: Contains details about the OAuth requirements
class OAuthCredentialsRequiredInfo:
    api_service: APIService      # The API service that needs authentication
    flows: List[OAuth2Flows]     # Available OAuth flows
    required_scopes: Set[str]    # Required OAuth scopes
  1. resume_info: Contains information needed to resume the tool execution
class ResumeToolExecutionInfo:
    type: str                    # Type of execution ("tool")
    tool_name: Action           # The original tool being executed
    tool_args: Dict             # Original arguments passed to the tool
    tool_schema: APISchema      # Schema of the API

​
Resuming Tool Execution

After refreshing the token or re-authenticating, you can resume the original tool execution using the resume_tool method of the WildcardClient. This method takes the ResumeToolExecutionInfo object that was provided in the exception: 
# Resume the tool execution using the resume_info from the exception
response = await wildcard_client.resume_tool(resume_info)
The resume_tool method will:
  1. Extract the original tool name, arguments, and schema from the resume info
  2. Re-run the tool with the same parameters using the new authentication
  3. Return the response as if the original call had succeeded
The resume_info contains everything needed to retry the operation. You can store it and resume the execution later, for example after the user re-authenticates in your UI.
Here’s a complete example of handling expired credentials and resuming execution: 
try:
    # Original tool execution
    response = await wildcard_client.run_tool_with_args(tool_name, **args)
except OAuthCredentialsRequiredException as e:
    # Store resume info for later use if needed
    stored_resume_info = e.resume_info
    
    # Implement token refresh logic
    await refresh_token(stored_resume_info)
    
    # Resume the original execution
    response = await wildcard_client.resume_tool(stored_resume_info)

​
Best Practices

  1. Always Handle Both Error Types: Be prepared to handle both AuthRequiredError and OAuthCredentialsRequiredException.
  2. Implement Token Refresh: Set up automatic token refresh to handle expired credentials gracefully.
  3. Store Resume Information: If token refresh fails, store the resume_info to retry the operation after re-authentication.
  4. Validate Scopes: Check if the refreshed token has all required scopes before resuming execution.

​
Next Steps