Agilicus Python SDK

Common errors

• requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: ...

  cause The Agilicus client failed to authenticate with the issuer. This is typically due to incorrect `AGILICUS_CLIENT_ID`, `AGILICUS_CLIENT_SECRET`, or `AGILICUS_ISSUER` configuration.
  fix Verify that your `AGILICUS_CLIENT_ID`, `AGILICUS_CLIENT_SECRET`, and `AGILICUS_ISSUER` environment variables or constructor arguments precisely match your Agilicus console settings and the correct issuer URL.

• requests.exceptions.HTTPError: 403 Client Error: Forbidden for url: ...

  cause The authenticated Agilicus client lacks the necessary permissions (scopes/roles) to perform the requested operation (e.g., `list_users` or accessing a specific protected resource).
  fix In your Agilicus console, check the client configuration associated with the `client_id` you are using. Ensure it has been granted the required scopes and roles for the API endpoints or resources you are trying to access.

• TypeError: Agilicus.__init__() missing 3 required positional arguments: 'client_id', 'client_secret', and 'issuer'

  cause The `Agilicus` client was instantiated without providing credentials, and the necessary environment variables (`AGILICUS_CLIENT_ID`, `AGILICUS_CLIENT_SECRET`, `AGILICUS_ISSUER`) were not set.
  fix Set the `AGILICUS_CLIENT_ID`, `AGILICUS_CLIENT_SECRET`, and `AGILICUS_ISSUER` environment variables before instantiating `agilicus.Agilicus()`, or pass these values directly as keyword arguments to the constructor (e.g., `agilicus.Agilicus(client_id=..., client_secret=..., issuer=...)`).

Warnings

• gotcha Many SDK operations require correct authentication credentials (CLIENT_ID, CLIENT_SECRET, ISSUER) and appropriate permissions for the client account. Misconfiguration often leads to 401 Unauthorized or 403 Forbidden errors.
  Fix: Ensure `AGILICUS_CLIENT_ID`, `AGILICUS_CLIENT_SECRET`, and `AGILICUS_ISSUER` environment variables are correctly set, or pass them directly to the `Agilicus()` constructor. Verify client permissions in your Agilicus console.
• gotcha API calls in the SDK often return `requests.Response` objects. Failing to check `response.raise_for_status()` or `response.ok` can lead to silently processing error responses (e.g., 404 Not Found) as if they were successful.
  Fix: Always call `response.raise_for_status()` after an API call (e.g., `client.get_protected_resource(...).raise_for_status()`) to automatically raise an `HTTPError` for bad responses, or explicitly check `response.ok` or `response.status_code`.
• gotcha The SDK primarily offers high-level wrappers. For advanced HTTP request features (e.g., custom headers, streaming responses, specific timeout handling) not directly exposed by SDK methods, you might need to access the underlying `client.session` object or fall back to raw `requests` calls.
  Fix: Investigate if the `client.session` attribute provides access to the underlying `requests.Session` object for more granular control, or consider direct `requests` calls for highly specific HTTP interactions.

Install

• pip install agilicus Install latest version

Imports

• Agilicus

  import agilicus
  client = agilicus.Agilicus()

Quickstart

Initializes the Agilicus client and demonstrates listing users and accessing a protected resource. Requires `AGILICUS_CLIENT_ID`, `AGILICUS_CLIENT_SECRET`, and `AGILICUS_ISSUER` environment variables to be set for authentication.

import os
import agilicus

# Ensure AGILICUS_CLIENT_ID, AGILICUS_CLIENT_SECRET, AGILICUS_ISSUER are set as environment variables.
# Example: os.environ['AGILICUS_CLIENT_ID'] = 'your_client_id_here'

# The Agilicus client automatically picks up credentials from environment variables.
# You can also pass them directly to the constructor.
client = agilicus.Agilicus()

try:
    # Example: List users (requires appropriate permissions)
    print("Attempting to list users...")
    users = client.list_users()
    if users:
        print(f"Successfully listed {len(users)} users. First user ID: {users[0].id}")
    else:
        print("No users found or client lacks permissions to list users.")

    # Example: Access a protected resource (replace with your actual resource path)
    print("\nAttempting to access a protected resource...")
    response = client.get_protected_resource("/api/v1/status") # Illustrative endpoint
    response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)
    print(f"Protected resource accessed successfully: {response.status_code}")
    print(response.json())

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure your Agilicus client is correctly configured with valid credentials and necessary permissions.")