API Keys

API keys provide a secure, long-lived authentication method for programmatic access to the Avatar API. They are ideal for automated pipelines, CI/CD integrations, and service-to-service communication where interactive login is not practical.

Overview

Unlike username/password authentication that produces short-lived JWT tokens, API keys:

• Are long-lived with configurable expiration (30 to 3,650 days)
• Can be revoked at any time without affecting the user's password
• Are scoped to a user and inherit that user's permissions
• Are suitable for headless/automated workflows

Creating an API Key

Python Client

import httpx

client = httpx.Client(base_url="https://your-avatar-instance.com/api")
# First authenticate with username/password
response = client.post("/login", json={"username": "user@example.com", "password": "your-password"})
token = response.json()["access_token"]

# Create an API key
response = client.post(
    "/api-keys",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "name": "my-etl-pipeline",
        "expiration_days": 365
    }
)
api_key = response.json()
print(f"API Key: {api_key['key']}")  # Save this — it won't be shown again

Parameters

Parameter	Type	Required	Description
name	string	Yes	A descriptive name for the key (max 256 characters)
expiration_days	integer	Yes	Key lifetime. Allowed values: 30, 60, 120, 365, 3650

warning

The full API key value is only returned once at creation time. Store it securely — it cannot be retrieved later.

Using an API Key

Once created, send the API key in the Authorization header with the api-key-v1 scheme:

curl -H "Authorization: api-key-v1 <your-api-key>" \
  https://your-avatar-instance.com/api/health

import httpx

client = httpx.Client(
    base_url="https://your-avatar-instance.com/api",
    headers={"Authorization": "api-key-v1 <your-api-key>"}
)
response = client.get("/health")

Managing API Keys

List All Keys

Retrieve all API keys associated with your account:

GET /api-keys

Returns key metadata (name, creation date, expiration) but not the key value itself.

Get Key Details

GET /api-keys/{api_key_id}

Revoke a Specific Key

DELETE /api-keys/{api_key_id}

Revoke All Keys

Revoke every API key associated with your account:

DELETE /api-keys

Admin: Revoke Keys for Other Users

Administrators can revoke keys by user ID or specific key ID:

DELETE /api-keys/admin?user_id={user_id}
DELETE /api-keys/admin?api_key_id={api_key_id}

Expiration Policies

Duration	Days	Recommended Use
1 month	30	Temporary access, testing
2 months	60	Short-term projects
4 months	120	Quarterly rotation
1 year	365	Standard automation
10 years	3,650	Long-lived service accounts

tip

We recommend rotating API keys periodically. Use shorter expiration periods for keys with broader access and longer periods for tightly scoped automation.

Security Best Practices

• Never commit API keys to version control
• Use environment variables to store keys in automated pipelines
• Rotate keys regularly and revoke unused ones
• Use descriptive names so you can identify what each key is used for
• Monitor usage through the admin panel to detect anomalies