OAuth CLI Kit

Common errors

• HTTPX_CLI_APP_CALLBACK_FAILURE

  cause The local redirect server failed to start or receive the authorization code, often due to an incorrect redirect URI configuration or a port conflict.
  fix Ensure the `redirect_uri` configured in your application and with the OAuth provider is `http://localhost:8000` (or your chosen custom port). Check if another process is already using port 8000, and ensure no firewalls are blocking it. You can specify a different `redirect_uri` port if needed.

• oauth_cli_kit.errors.OAuthCliKitError: PKCE verification failed

  cause The OAuth provider returned an authorization code, but the PKCE code_verifier did not match during token exchange, indicating a mismatch or an unsupported provider.
  fix Verify that your OAuth provider correctly supports and implements PKCE. Ensure no intermediate proxies are modifying the request/response. Double-check your `client_id` and other OAuth configuration details.

• ModuleNotFoundError: No module named 'typer'

  cause Although `typer` is a dependency of `oauth-cli-kit`, some environments (especially if installing with `--no-deps` or in custom setups) might not automatically install it.
  fix Explicitly install `typer`: `pip install typer` or ensure you are installing `oauth-cli-kit` in a clean environment where dependencies are resolved normally.

• oauth_cli_kit.errors.OAuthCliKitError: Failed to open browser: ...

  cause The library failed to automatically open the default web browser to the authorization URL, often due to environmental issues or lack of a default browser configuration.
  fix Manually copy the authorization URL (which is usually printed to the console before the error) and paste it into your web browser. Complete the authentication flow there, and the local server should still capture the redirect.

Warnings

• breaking As a 0.x.x version library, the API is not yet stable. Expect potential breaking changes in minor releases as the library evolves.
  Fix: Review the GitHub repository's changelog or releases notes before upgrading, especially when moving between minor versions (e.g., 0.1.x to 0.2.x).
• gotcha The library automatically starts a temporary local HTTP server to handle the OAuth redirect URI (e.g., `http://localhost:8000`). Ensure this URI is registered with your OAuth provider and is accessible on the client machine.
  Fix: Verify that your OAuth provider's registered redirect URI exactly matches the `redirect_uri` you pass to `OAuthCliApp` and that no firewall or other process is blocking port 8000 (or your chosen custom port).
• gotcha By default, the library implements the Authorization Code Grant flow with PKCE. Confirm that your OAuth 2.0 provider supports PKCE, as some older or less standard implementations might not.
  Fix: Consult your OAuth provider's documentation. If PKCE is not supported, you might need to use a different library or a different flow entirely, as this library is strongly oriented towards PKCE.
• gotcha The `oauth-cli-kit` only facilitates obtaining access and refresh tokens. It does not handle the secure storage, retrieval, or refreshing of these tokens. This must be implemented by your application.
  Fix: Implement a secure token storage mechanism (e.g., keyring, encrypted file) and a token refreshing strategy using the obtained refresh token within your CLI application.

Install

• pip install oauth-cli-kit Install latest version

Imports

• OAuthCliApp

  from oauth_cli_kit import OAuthCliApp

Quickstart

This quickstart demonstrates how to initiate an OAuth 2.0 PKCE flow using `OAuthCliApp`. It will open a browser for user authentication and then process the callback locally. Remember to replace placeholder URLs and client IDs with your actual provider details, ideally via environment variables, for a successful authentication.

import os
from oauth_cli_kit import OAuthCliApp

def main():
    # Replace these placeholders with your actual OAuth provider details or set as environment variables.
    client_id = os.environ.get("OAUTH_CLI_KIT_CLIENT_ID", "YOUR_CLIENT_ID_HERE")
    auth_url = os.environ.get("OAUTH_CLI_KIT_AUTH_URL", "https://example.com/oauth/authorize")
    token_url = os.environ.get("OAUTH_CLI_KIT_TOKEN_URL", "https://example.com/oauth/token")
    redirect_uri = os.environ.get("OAUTH_CLI_KIT_REDIRECT_URI", "http://localhost:8000")
    scope = os.environ.get("OAUTH_CLI_KIT_SCOPE", "profile email openid")

    if client_id == "YOUR_CLIENT_ID_HERE" or auth_url == "https://example.com/oauth/authorize":
        print("WARNING: Using placeholder OAuth credentials. ")
        print("Please configure OAUTH_CLI_KIT_CLIENT_ID, OAUTH_CLI_KIT_AUTH_URL, ")
        print("OAUTH_CLI_KIT_TOKEN_URL environment variables or replace placeholders in the code ")
        print("with your actual OAuth provider details to run a successful flow.")
        print(f"  Attempting with: Client ID={client_id}, Auth URL={auth_url}, Token URL={token_url}")

    print("Initiating OAuth 2.0 PKCE flow...")

    try:
        oauth_app = OAuthCliApp(
            client_id=client_id,
            auth_url=auth_url,
            token_url=token_url,
            redirect_uri=redirect_uri,
            scope=scope,
        )
        token_response = oauth_app.run_flow() # This call opens browser and waits
        print("\n--- OAuth Flow Successful ---")
        print(f"Access Token: {token_response.access_token[:10]}... (truncated)")
        if token_response.refresh_token:
            print(f"Refresh Token: {token_response.refresh_token[:10]}... (truncated)")
        print(f"Token Type: {token_response.token_type}")
        print(f"Expires In: {token_response.expires_in} seconds")
        if token_response.id_token:
            print(f"ID Token (JWT): {token_response.id_token[:10]}... (truncated)")

    except Exception as e:
        print(f"\n--- OAuth Flow Failed ---")
        print(f"Error: {e}")
        print("Please check your configuration, network connection, and browser interaction.")

if __name__ == "__main__":
    main()