{"id":6527,"library":"authy","title":"Authy Python API Client","description":"The `authy` library is the official Python client for the Authy API, providing functionalities for two-factor authentication, including user registration, token verification, and sending SMS or push notifications. As of version 2.2.6, it offers a stable interface to integrate Authy's services into Python applications, supporting Python 3.6+. Its release cadence is low, focusing on stability and maintenance.","status":"active","version":"2.2.6","language":"en","source_language":"en","source_url":"https://github.com/authy/authy-python","tags":["authentication","2fa","security","authy","api-client","sms","mfa"],"install":[{"cmd":"pip install authy","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for making HTTP requests to the Authy API.","package":"requests","optional":false}],"imports":[{"symbol":"AuthyApiClient","correct":"from authy import AuthyApiClient"},{"note":"Useful for specific error handling related to Authy API interactions.","symbol":"AuthyException","correct":"from authy.authy_exceptions import AuthyException"}],"quickstart":{"code":"import os\nfrom authy import AuthyApiClient\nfrom authy.authy_exceptions import AuthyException\n\n# IMPORTANT: Replace 'YOUR_AUTHY_API_KEY_HERE' with your actual Authy API key\n# or, preferably, set it as an environment variable: export AUTHY_API_KEY='...'\napi_key = os.environ.get('AUTHY_API_KEY', 'YOUR_AUTHY_API_KEY_HERE')\n\nif api_key == 'YOUR_AUTHY_API_KEY_HERE' or not api_key:\n    print(\"WARNING: Please set the AUTHY_API_KEY environment variable \"\n          \"or replace 'YOUR_AUTHY_API_KEY_HERE' with your actual key to run this example.\")\n    # In a real application, you might raise an error or handle this differently.\n    # For a runnable quickstart, we'll try to proceed but expect failures if key is invalid.\n\ntry:\n    authy_api = AuthyApiClient(api_key)\n\n    # --- Example 1: Check User Status (requires an existing Authy ID) ---\n    # Replace with an actual Authy ID from a user registered in your Authy app.\n    # If using a dummy ID, this call will likely fail with a \"User not found\" error.\n    sample_authy_id = \"1234567\" # Example: Replace with a real Authy ID if you have one\n\n    print(f\"\\n--- Attempting to get status for Authy ID: {sample_authy_id} ---\")\n    user_status_response = authy_api.users.status(sample_authy_id)\n\n    if user_status_response.ok():\n        print(f\"SUCCESS: User {sample_authy_id} status: {user_status_response.content}\")\n        # Example of accessing content: user_status_response.content['user']['status']\n    else:\n        print(f\"FAILURE: Could not get user status. Errors: {user_status_response.errors()}\")\n        print(f\"Full API response content: {user_status_response.content}\")\n\n    # --- Example 2: Verify a 2FA Token (requires an existing Authy ID and a token) ---\n    # Replace with a real Authy ID and a real token generated for that user.\n    # If using dummy values, this call will likely fail with \"invalid token\" or \"user not found\".\n    sample_token_authy_id = sample_authy_id # Use the same dummy ID for consistency\n    sample_token_code = \"0000000\" # Example: Replace with a real 2FA token\n\n    print(f\"\\n--- Attempting to verify token '{sample_token_code}' for Authy ID: {sample_token_authy_id} ---\")\n    token_verification_response = authy_api.tokens.verify(sample_token_authy_id, sample_token_code)\n\n    if token_verification_response.ok():\n        print(f\"SUCCESS: Token '{sample_token_code}' verified for Authy ID {sample_token_authy_id}.\")\n        # Example of accessing content: token_verification_response.content['token']['message']\n    else:\n        print(f\"FAILURE: Token verification failed. Errors: {token_verification_response.errors()}\")\n        print(f\"Full API response content: {token_verification_response.content}\")\n\nexcept AuthyException as e:\n    print(f\"\\nAn Authy API specific error occurred: {e}\")\nexcept Exception as e:\n    print(f\"\\nAn unexpected error occurred: {e}\")\n\nprint(\"\\n--- Quickstart example finished ---\")","lang":"python","description":"Initializes the Authy API client using an API key and demonstrates how to check user status and verify a 2FA token. Ensure your `AUTHY_API_KEY` environment variable is set or replace the placeholder. Operations will likely fail without a valid API key, Authy ID, and a real token."},"warnings":[{"fix":"Always check `response.ok()` after an API call. If `False`, inspect `response.errors()` or `response.content` for details on the failure.","message":"Authy API calls return response objects that require explicit checking with `.ok()` to determine success or failure. Direct access to `.content` without checking `.ok()` first can lead to processing error messages as valid data.","severity":"gotcha","affected_versions":"All 2.x.x"},{"fix":"Store API keys securely (e.g., in environment variables) and load them dynamically based on your application's environment configuration.","message":"The library uses a single API key for all operations. Ensure you are using the correct API key (e.g., 'production' vs. 'sandbox') for your target environment. Mixing them will lead to `AuthyException` or unexpected behavior (e.g., users not found).","severity":"gotcha","affected_versions":"All 2.x.x"},{"fix":"Integrate the user registration flow to create Authy users and store their `authy_id` alongside your internal user IDs.","message":"Authy IDs are internal to Authy and distinct from your application's user IDs. You must first register a user with Authy (`authy_api.users.create`) to obtain an `authy_id` before performing other user-specific operations like sending tokens or verifying.","severity":"gotcha","affected_versions":"All 2.x.x"},{"fix":"Consult the Authy API documentation or `print(response.content)` to understand the structure of the API responses for each endpoint.","message":"The `authy` client's methods (`users`, `tokens`, `phones`) return specific response objects. Accessing data like an Authy ID, status, or verification result often requires drilling into the `.content` attribute, which is a dictionary (e.g., `user_registration_response.content['user']['id']`).","severity":"gotcha","affected_versions":"All 2.x.x"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Install the 'authy' package using pip: 'pip install authy'.","cause":"The 'authy' library is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'authy'"},{"fix":"Upgrade the 'requests' library to the latest version using pip: 'pip install --upgrade requests'.","cause":"The 'requests' library version is outdated and lacks the 'to_native_string' function.","error":"ImportError: cannot import name 'to_native_string'"},{"fix":"Ensure the correct import statement: 'from authy.api import AuthyApiClient'. If the issue persists, upgrade the 'authy' library: 'pip install --upgrade authy'.","cause":"Incorrect import statement or outdated 'authy' library version.","error":"AttributeError: module 'authy' has no attribute 'AuthyApiClient'"},{"fix":"Verify the API key is correct and has the necessary permissions. Check network connectivity and ensure the Authy service is operational.","cause":"The 'authy' API client returned 'None', possibly due to an invalid API key or network issue.","error":"TypeError: 'NoneType' object is not subscriptable"},{"fix":"Ensure the server and client devices have synchronized clocks. Verify the TOTP generation parameters (e.g., time step, algorithm) match between the server and client.","cause":"The provided TOTP token does not match the expected value, possibly due to time synchronization issues.","error":"ValueError: Invalid TOTP token"}]}