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(api_key="your-api-key-here")

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", api_key="your-api-key-here")

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¶

API Key Authentication¶

The Avatar Python client authenticates using an API key, which is well suited to automated scripts and CI/CD pipelines. Generate an API key from the web application (Settings → API Keys), then pass it to the Manager:

from avatars import Manager

manager = Manager(
    base_url="https://avatar.yourcompany.com",
    api_key="your-api-key-here"
)
# Ready to use immediately.

The API key is sent on every request in the Authorization header using the api-key-v1 scheme. It can also be provided via the AVATAR_API_KEY environment variable instead of the api_key argument.

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)