AvalAI API Authentication

This guide explains how to authenticate with the AvalAI API.

API Keys

All requests to the AvalAI API must include an API key. Your API keys are available in the AvalAI Dashboard.

Security Warning

Keep your API keys secure! Do not expose them in client-side code or public repositories. API keys should only be used in server-side code.

Authentication Methods

Bearer Token Authentication

The recommended way to authenticate with the AvalAI API is using Bearer token authentication in the Authorization header:

curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
 "model": "gpt-5.6-luna",
 "messages": [{"role": "user", "content": "Hello!"}]
}'

Responses API version

Use this version when the selected model supports /v1/responses. messages moves to input, and the final text is read from response.output_text.

curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '
  {
    "model": "gpt-5.6-luna",
    "input": "Hello!",
    "instructions": "You are a helpful assistant."
  }'

• messages → input
• system message → instructions or a developer item
• choices[0].message.content → response.output_text
• for tools and multimodal output, inspect response.output by item type.

Client Libraries

When using client libraries, you can configure the API key and base URL during client initialization:

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",  # AvalAI API endpoint
)

JavaScript/TypeScript

import { OpenAI } from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY, // Use environment variables
  baseURL: "https://api.avalai.ir/v1",
});

Go

package main

import (
	"os"

	openai "github.com/openai/openai-go"
	"github.com/openai/openai-go/option"
)

func main() {
	client := openai.NewClient(
		option.WithAPIKey(os.Getenv("AVALAI_API_KEY")),
		option.WithBaseURL("https://api.avalai.ir/v1"),
	)
	_ = client
}

API Key Best Practices

1. Never share your API keys: Treat your API keys like passwords.
2. Use environment variables: Store API keys in environment variables instead of hardcoding them.
3. Create separate API keys: Use different API keys for development, testing, and production environments.
4. Restrict API key permissions: Create keys with the minimum required permissions.
5. Rotate API keys regularly: Regenerate your API keys periodically for enhanced security.
6. Monitor API key usage: Regularly check your API usage for unauthorized activities.

Enterprise Access Controls

OpenAI's RBAC and Admin API documentation is a useful design pattern: separate organization-level administration from project-level runtime access, assign permissions through groups or service accounts, and verify access with a non-owner account before broad rollout. AvalAI does not expose the same OpenAI organization management APIs, so map the pattern to the controls available in your AvalAI dashboard and your own application IAM.

For production AvalAI deployments:

• issue separate keys per environment, service, tenant, or reseller when isolation matters;
• keep admin, billing, support, and model-serving credentials separate;
• grant only the routes and models each workload needs, when key restrictions are available;
• remove unused keys, stale users, and old CI secrets during every access review;
• record key creation, deletion, rotation, rate-limit, and permission changes in your own audit trail.

Admin Automation Boundaries

OpenAI Admin APIs use a separate Admin API key and are not valid for normal model endpoints. AvalAI does not currently document compatible Admin APIs, so do not configure OpenAI admin-key environment variables, call OpenAI organization administration routes through AvalAI, or assume OpenAI SDK admin helpers manage AvalAI keys.

Automate AvalAI administration only through documented AvalAI dashboard/API surfaces. If you need user invites, key lifecycle automation, rate-limit changes, or audit-log exports, treat them as platform-administration workflows and confirm the supported AvalAI route before building scripts.

IP Allowlists and Network Identity

OpenAI publishes egress IP ranges for OpenAI-operated products such as ChatGPT integrations and Codex cloud. Those ranges identify traffic from OpenAI infrastructure, not a specific customer, workspace, or AvalAI route. Do not use OpenAI IP ranges to authenticate traffic from your app to AvalAI or to represent AvalAI provider traffic.

For network controls:

• authenticate every AvalAI request with Authorization: Bearer $AVALAI_API_KEY;
• restrict outbound access from your servers or CI runners to https://api.avalai.ir/v1 where practical;
• verify inbound webhooks, tools, and callbacks with signatures, OAuth, mTLS, or shared secrets when the upstream service supports them;
• keep IP allowlists service-specific and refresh them automatically when a provider publishes changing ranges.

Server and Workload Identity Planning

OpenAI's enterprise authentication docs include workload identity federation, where trusted cloud workloads exchange OIDC tokens for short-lived API access tokens instead of storing long-lived API keys. AvalAI does not currently publish a workload identity token-exchange endpoint, so treat this as an architecture pattern rather than an AvalAI feature.

For production AvalAI apps today:

• keep AVALAI_API_KEY only in server-side secret stores such as your cloud secret manager or CI secret vault,
• issue your own short-lived session token from your backend to browsers or mobile clients,
• map each service, environment, and tenant to a separate AvalAI key when isolation matters,
• log avalai-request-id, endpoint, model, and hashed safety_identifier so requests remain auditable without exposing raw PII,
• rotate keys immediately when a deployment, employee device, CI runner, or repository secret is suspected to be compromised.

If AvalAI later adds workload identity, expect to configure a trusted issuer, match workload claims to a service account or API key scope, grant least-privilege permissions, and monitor token-exchange failures separately from normal API request failures.

Organization IDs

Warning

Feature Not Implemented!

This functionality is currently under development and not yet available in AvalAI. We’ll announce its release through our official channels. Stay tuned for updates!

Until organization routing is available, do not send organization headers or SDK organization options. Use separate API keys, environments, projects, or reseller/user metadata in your own application to separate traffic and billing.

Rate Limiting

API requests are subject to rate limiting. When you exceed your rate limits, you'll receive a 429 Too Many Requests response. For more information, see the Rate Limits documentation.

API Key Management

You can manage your API keys in the AvalAI Dashboard:

1. Create new API keys
2. Delete existing API keys
3. View API key usage statistics
4. Set permissions and restrictions for API keys

Troubleshooting Authentication Issues

If you're experiencing authentication issues:

1. Verify that you're using the correct API key
2. Check that the API key is active and not expired
3. Ensure you're using the correct authentication method
4. Confirm that the API key has the necessary permissions
5. Check your rate limits to ensure you haven't exceeded them

If you continue to experience issues, contact AvalAI Support.