Skip to main content
The Avala SDK uses API keys to authenticate requests. All requests must include a valid API key with appropriate permissions.

​
Get your API key

1

Log in to Avala

Navigate to app.avala.ai
2

Open API settings

Go to Settings → API Keys
3

Generate a new key

Click Create API Key and give it a descriptive name
4

Copy the key

Copy the generated key—it starts with avk_
API keys are shown only once. Store your key securely—if you lose it, you’ll need to generate a new one.
The simplest and most secure method is to set the AVALA_API_KEY environment variable: 
export AVALA_API_KEY="avk_your_api_key"
The client will automatically read this variable: 
from avala import Client

client = Client()  # Reads AVALA_API_KEY automatically
Add the export line to your shell profile (.bashrc, .zshrc, etc.) to persist the variable across sessions.

​
Pass the key explicitly

Alternatively, pass the API key directly when creating the client: 
from avala import Client

client = Client(api_key="avk_your_api_key")
Never hardcode API keys in source code that’s committed to version control. Use environment variables or secret management tools instead.

​
Use a .env file

For local development, use a .env file to manage secrets:
1

Create a .env file

.env
AVALA_API_KEY=avk_your_api_key
2

Add .env to .gitignore

.gitignore
.env
3

Load with python-dotenv

pip install python-dotenv

from dotenv import load_dotenv
from avala import Client

load_dotenv()  # Loads .env into environment variables
client = Client()  # Reads AVALA_API_KEY from environment

​
Configure async client

The async client uses the same authentication methods: 
from avala import AsyncClient

# From environment variable
async with AsyncClient() as client:
    datasets = await client.datasets.list()

# Or pass explicitly
async with AsyncClient(api_key="avk_your_api_key") as client:
    datasets = await client.datasets.list()

​
Handle authentication errors

The SDK raises AuthenticationError when the API key is invalid or missing: 
from avala import Client
from avala.errors import AuthenticationError

try:
    client = Client(api_key="invalid_key")
    datasets = client.datasets.list()
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
    print("Check that your API key is valid")
If you don’t provide an API key and AVALA_API_KEY is not set, the client will raise a ValueError during initialization—before making any API requests.

​
Production deployment

​
Environment variables

For production deployments, use your platform’s secret management: 
heroku config:set AVALA_API_KEY=avk_your_api_key

​
AWS Secrets Manager

import boto3
from avala import Client

def get_secret():
    client = boto3.client('secretsmanager', region_name='us-east-1')
    response = client.get_secret_value(SecretId='avala/api-key')
    return response['SecretString']

avala_client = Client(api_key=get_secret())

​
Google Cloud Secret Manager

from google.cloud import secretmanager
from avala import Client

def get_secret():
    client = secretmanager.SecretManagerServiceClient()
    name = "projects/PROJECT_ID/secrets/avala-api-key/versions/latest"
    response = client.access_secret_version(request={"name": name})
    return response.payload.data.decode('UTF-8')

avala_client = Client(api_key=get_secret())

​
Security best practices

Always use environment variables or secret management systems. Add .env to .gitignore and audit your repository for accidentally committed secrets.
Generate new API keys periodically and revoke old ones. This limits the impact of a potential key compromise.
Create different API keys for development, staging, and production. This allows you to revoke a compromised key without affecting other environments.
Use the principle of least privilege. If Avala supports scoped API keys in the future, grant only the minimum permissions needed.
Regularly review API key usage in your Avala dashboard to detect unauthorized access.

​
Custom base URL

By default, the SDK connects to https://api.avala.ai/api/v1. For testing or on-premises deployments, override the base URL: 
from avala import Client

client = Client(
    api_key="avk_your_api_key",
    base_url="https://custom-api.example.com/api/v1"
)
Or use the AVALA_BASE_URL environment variable: 
export AVALA_BASE_URL="https://custom-api.example.com/api/v1"
export AVALA_API_KEY="avk_your_api_key"
The SDK enforces HTTPS by default. To use HTTP for local development (e.g., http://localhost), set AVALA_ALLOW_INSECURE_BASE_URL=true. This is only allowed for localhost addresses.

​
Local development

export AVALA_BASE_URL="http://localhost:8000/api/v1"
export AVALA_ALLOW_INSECURE_BASE_URL=true
export AVALA_API_KEY="avk_test_key"

​
Troubleshooting

The SDK couldn’t find your API key. Ensure AVALA_API_KEY is set or pass api_key= explicitly:
# Check if the variable is set
import os
print(os.environ.get('AVALA_API_KEY'))  # Should print your key
Your API key is incorrect or has been revoked. Generate a new key from the Avala dashboard and update your configuration.
Some API keys may have expiration dates. Check your dashboard and generate a new key if needed.
The base_url must be a valid URL with a scheme (http/https) and host. Check your AVALA_BASE_URL environment variable or base_url parameter.

​
Next steps

Quickstart

Make your first API calls with the authenticated client

Error Handling

Handle authentication errors gracefully

Build docs developers (and LLMs) love

Get started for freeTalk to us