chipflow.auth
=============

.. py:module:: chipflow.auth

.. autoapi-nested-parse::

   ChipFlow authentication helper module.

   Handles authentication for ChipFlow API with multiple fallback methods:
   1. Environment variable CHIPFLOW_API_KEY
   2. GitHub CLI token authentication (if gh is available)
   3. OAuth 2.0 Device Flow



Exceptions
----------

.. autoapisummary::

   chipflow.auth.AuthenticationError


Functions
---------

.. autoapisummary::

   chipflow.auth.get_credentials_file
   chipflow.auth.save_api_key
   chipflow.auth.load_saved_api_key
   chipflow.auth.is_gh_authenticated
   chipflow.auth.get_gh_token
   chipflow.auth.authenticate_with_github_token
   chipflow.auth.authenticate_with_device_flow
   chipflow.auth.get_api_key
   chipflow.auth.logout


Module Contents
---------------

.. py:exception:: AuthenticationError

   Bases: :py:obj:`Exception`


   Exception raised when authentication fails.


.. py:function:: get_credentials_file()

   Get path to credentials file.


.. py:function:: save_api_key(api_key)

   Save API key to credentials file.


.. py:function:: load_saved_api_key()

   Load API key from credentials file if it exists.


.. py:function:: is_gh_authenticated()

   Check if GitHub CLI is installed and authenticated.


.. py:function:: get_gh_token()

   Get GitHub token from gh CLI.


.. py:function:: authenticate_with_github_token(api_origin, interactive = True)

   Authenticate using GitHub CLI token.

   Args:
       api_origin: ChipFlow API origin URL
       interactive: Whether to show interactive messages

   Returns:
       API key on success, None on failure


.. py:function:: authenticate_with_device_flow(api_origin, interactive = True)

   Authenticate using OAuth 2.0 Device Flow.

   Args:
       api_origin: ChipFlow API origin URL
       interactive: Whether to show interactive messages

   Returns:
       API key on success, raises AuthenticationError on failure


.. py:function:: get_api_key(api_origin = None, interactive = True, force_login = False)

   Get API key using the following priority:
   1. CHIPFLOW_API_KEY environment variable
   2. Saved credentials file (unless force_login is True)
   3. GitHub CLI token authentication
   4. Device flow authentication

   Args:
       api_origin: ChipFlow API origin URL (defaults to CHIPFLOW_API_ORIGIN env var or production)
       interactive: Whether to show interactive messages and prompts
       force_login: Force re-authentication even if credentials exist

   Returns:
       API key string

   Raises:
       AuthenticationError: If all authentication methods fail


.. py:function:: logout()

   Remove saved credentials.