Configuration¶

This guide explains how to configure the Avatar Python client to connect to different server environments.

Server Connection Basics¶

The Avatar Python client needs to know which server to connect to. By default, it connects to Octopize’s SaaS server at https://www.octopize.app, but you can configure it to connect to your own on-premise installation.

Default Configuration (SaaS Server)¶

If you’re using Octopize’s cloud service, you don’t need to provide any URL configuration:

from avatars import Manager

# Connects to https://www.octopize.app by default
manager = Manager()
manager.authenticate(username="your_username", password="your_password")

On-Premise Server Configuration¶

If you’re using an on-premise installation, you need to tell the client where your server is located:

from avatars import Manager

# Connect to your on-premise server
manager = Manager(base_url="https://avatar.yourcompany.com")
manager.authenticate(username="your_username", password="your_password")

The base_url parameter should be the base URL of your Avatar server (without the /api suffix).

Note

For users migrating from earlier versions: The older pattern of specifying base_url="https://avatar.yourcompany.com/api" with the /api suffix still works for backward compatibility, but the recommended approach is to use the base URL without the suffix.

Authentication Methods¶

Username and Password¶

The traditional authentication method uses username and password:

from avatars import Manager

manager = Manager(base_url="https://avatar.yourcompany.com")
manager.authenticate(username="user", password="pass")

API Key Authentication¶

You can also authenticate using an API key, which is particularly useful for automated scripts and CI/CD pipelines:

from avatars import Manager

manager = Manager(
    base_url="https://avatar.yourcompany.com",
    api_key="your-api-key-here"
)
# No need to call authenticate() - you're already authenticated!

Important

When using API key authentication, do not call authenticate(). The API key is active immediately upon initialization. Attempting to call authenticate() with an API key will raise an error.

Advanced Configuration Options¶

SSL Certificate Verification¶

For on-premise deployments without dedicated SSL certificates, you can disable SSL verification:

from avatars import Manager, ApiClient

manager = Manager(
    api_client=ApiClient(
        base_url="https://avatar.yourcompany.com",
        should_verify_ssl=False
    )
)

Warning

Disabling SSL verification should only be done in trusted environments. It reduces security by making your connection vulnerable to man-in-the-middle attacks.

Using ClientConfig¶

For more control over all configuration options, you can use a ClientConfig object:

from avatars import Manager
from avatars.client_config import ClientConfig

config = ClientConfig(
    base_url="https://avatar.yourcompany.com",
    should_verify_ssl=False,
    timeout=120  # Custom timeout in seconds
)

manager = Manager(config=config)

Environment Variables¶

You can also configure the client using environment variables with the AVATAR_ prefix:

export AVATAR_BASE_URL="https://avatar.yourcompany.com"
export AVATAR_API_KEY="your-api-key-here"
export AVATAR_SHOULD_VERIFY_SSL="false"
export AVATAR_TIMEOUT="120"

Then in Python:

from avatars import Manager

# Configuration is automatically loaded from environment variables
manager = Manager()

Configuration Priority¶

When multiple configuration sources are provided, they follow this priority order (highest to lowest):

Parameters passed directly to Manager() constructor (base_url, api_key, etc.)
ClientConfig object passed to Manager()
Environment variables with AVATAR_ prefix
Default values (SaaS server)