Agilicus Python SDK

1.415.0 verified Fri Apr 17 auth: no python

The Agilicus Python SDK provides a client for interacting with Agilicus APIs, facilitating secure access to protected resources and management operations. It is currently at version 1.415.0 and appears to follow a rapid release cadence based on frequent version bumps on PyPI, often without detailed public release notes.

pip install agilicus

Common errors

error 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.

error 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.

error 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.

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.")