Overview

This guide explains how to authenticate with Pay-i, regardless of which operational approach you choose - Direct Provider Call with Telemetry or Proxy Routing.

Authentication for Direct Provider Call with Telemetry

When using the Direct Provider Call with Telemetry approach, you authenticate with Pay-i by initializing the SDK with your API key. The recommended approach is to use environment variables:

import os
from payi import Payi
from payi.lib.instrument import payi_instrument

# Environment variables - this works for both public and private deployments
os.environ["PAYI_API_KEY"] = "YOUR_PAYI_API_KEY"  # Set before running in production
os.environ["PAYI_BASE_URL"] = "YOUR_API_ENDPOINT"  # Only needed for private deployments

# Initialize Pay-i - no parameters needed when using environment variables
payi = Payi()
payi_instrument(payi)

Alternatively, you can pass parameters directly, though environment variables are preferred for production:

from payi import Payi
from payi.lib.instrument import payi_instrument

# Initialize Pay-i with explicit parameters (environment variables preferred)
payi = Payi(api_key="YOUR_PAYI_API_KEY")
payi_instrument(payi)

Note: Using environment variables (PAYI_API_KEY and PAYI_BASE_URL) allows your code to work seamlessly in both public and private deployments without hardcoding sensitive values or requiring code changes when moving between environments.

Authentication for Proxy Routing

When using the Proxy Routing approach, you need to include your Pay-i API key in request headers and direct requests to the appropriate Pay-i endpoint. The recommended approach is to use environment variables:

import os
from openai import OpenAI
from payi.lib.helpers import payi_openai_url

# Set environment variables (in a production environment, these would be
# configured in your deployment platform or .env file)
os.environ["OPENAI_API_KEY"] = "YOUR_OPENAI_API_KEY"
os.environ["PAYI_API_KEY"] = "YOUR_PAYI_API_KEY"
os.environ["PAYI_BASE_URL"] = "YOUR_API_ENDPOINT"  # Only needed for private deployments

# Get keys from environment (best practice)
openai_key = os.environ["OPENAI_API_KEY"]
payi_key = os.environ["PAYI_API_KEY"]

# Use helper function to get the correct endpoint URL
# This will automatically use PAYI_BASE_URL if it's set
payi_openai_endpoint = payi_openai_url()

# Create client with Pay-i authentication
client = OpenAI(
    api_key=openai_key,
    base_url=payi_openai_endpoint,
    default_headers={"xProxy-Api-Key": payi_key}  # Pay-i authentication
)

# Now use the client as normal - requests will be routed through Pay-i
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}]
)

Using environment variables allows your code to work seamlessly in both public and private deployments without requiring code changes. The URL helper functions automatically detect your deployment type based on the PAYI_BASE_URL environment variable.

Helper Functions for Provider Endpoints

Pay-i provides helper functions to construct the correct provider-specific endpoints:

payi_openai_url() - For OpenAI endpoints
payi_azure_openai_url() - For Azure OpenAI endpoints
payi_anthropic_url() - For Anthropic endpoints
payi_aws_bedrock_url() - For AWS Bedrock endpoints

These helpers automatically handle constructing the correct URLs based on your deployment type.

Note: Google Vertex AI is currently supported only through the Direct Provider Call with Telemetry approach, not via proxy routing.

Provider-Specific Examples

For complete code examples showing authentication and configuration with different providers, refer to the provider-specific guides:

Environment Variables

The Pay-i SDK can automatically pick up authentication information from environment variables, which is the recommended approach for production environments. For a complete guide to environment variables in Pay-i, see the Environment Variables documentation.

Key environment variables for authentication include:

PAYI_API_KEY: Your Pay-i API key
PAYI_BASE_URL: Your Pay-i base URL (only needed for private deployments)

API Key Management

The recommended pattern for managing Pay-i API keys is to map them from your secret store to environment variables:

Secret Store (Vault/AWS Secrets/etc.) → Environment Variables → Application

This approach works seamlessly across all deployment environments:

# In Kubernetes, you would map secrets to environment variables in your deployment YAML
# In your application code, simply read from the environment:
import os
from payi import Payi

# Keys are automatically loaded from environment variables
payi = Payi()  # Uses PAYI_API_KEY environment variable

Key security best practices:

Never hardcode API keys in your application code
Use your platform's secret management (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
Configure your deployment pipeline to map secrets to the expected environment variables
Rotate keys periodically following your security policies
Use different API keys for different environments (development, staging, production)

For more information about Pay-i API keys and how to manage them, see the Pay-i API Keys documentation.