Overview

Environment variables provide a secure and flexible way to configure the Pay-i SDK without hardcoding sensitive information in your source code. This approach is particularly important for API keys and other credentials, making your application more secure and easier to deploy across different environments.

This guide explains the environment variables supported by the Pay-i SDK and how to use them effectively in your applications.

Supported Environment Variables

The Pay-i SDK supports the following environment variables:

For detailed information about the Payi and AsyncPayi client classes, see the Pay-i Client Classes documentation.

Using Environment Variables

Authentication with PAYI_API_KEY

The PAYI_API_KEY environment variable allows you to securely store your Pay-i API key outside your code:

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

# The SDK will automatically use PAYI_API_KEY if no api_key is provided
payi = Payi()  # Automatically reads from PAYI_API_KEY environment variable

# Initialize instrumentation
payi_instrument()  # Initialize Pay-i instrumentation (defaults to Ingest mode)

This approach offers several benefits:

• Security: Your API key isn't hardcoded in source code
• Flexibility: Different environments (development, staging, production) can use different keys

Custom API Endpoints with PAYI_BASE_URL

The PAYI_BASE_URL environment variable allows you to specify a custom API endpoint:

import os
from payi import Payi
from payi.lib.helpers import payi_openai_url

# The SDK will automatically use PAYI_BASE_URL if no base_url is provided
payi = Payi()  # Uses PAYI_BASE_URL environment variable for the endpoint

# Helper functions also use PAYI_BASE_URL when payi_base_url is None
openai_proxy_url = payi_openai_url()  # Uses PAYI_BASE_URL environment variable 

This is particularly useful for:

• Private Deployments: Enterprise customers with private Pay-i deployments
• Testing Environments: Pointing to staging or testing environments
• Multi-Region Deployments: Using region-specific API endpoints

Setting Environment Variables

Local Development

For Python SDK clients, we recommend using .env files as the default approach for setting environment variables in local development. This provides several advantages:

• Durability across sessions: Environment variables persist between terminal sessions
• No external setup required in IDEs: Most modern IDEs automatically recognize .env files
• Portability: Easy to maintain consistent configuration across different development environments

Using .env Files (Recommended)

For development with Python, you'll need to use the python-dotenv package to work with .env files:

from dotenv import load_dotenv
import os
from payi import Payi

# Load environment variables from .env file
load_dotenv()

# Now you can access the variables
payi = Payi()  # Automatically reads from PAYI_API_KEY environment variable

A sample .env file:

PAYI_API_KEY=your-api-key-here
PAYI_BASE_URL=https://custom.pay-i.com

IMPORTANT: Never commit .env files to version control. Add them to your .gitignore file to prevent accidental exposure of credentials.

Setting Environment Variables in Shell

For non-Python use cases or when .env files aren't suitable, you can set environment variables directly in your terminal session:

export PAYI_API_KEY="your-api-key-here"
export PAYI_BASE_URL="https://custom.pay-i.com"  # For private deployments

set PAYI_API_KEY=your-api-key-here
set PAYI_BASE_URL=https://custom.pay-i.com   # For private deployments

$env:PAYI_API_KEY="your-api-key-here"
$env:PAYI_BASE_URL="https://custom.pay-i.com"   # For private deployments

Production Deployment

In production environments, manage your Pay-i API keys like any other sensitive credentials:

• Use the appropriate secrets management service for your deployment environment
• Follow your organization's established practices for secrets management
• Avoid storing secrets directly in configuration files or code repositories
• Implement proper access controls to limit who can view or modify these secrets

The specific mechanism will depend on your infrastructure, cloud provider, and organizational requirements. Most modern deployment platforms provide integrated secrets management capabilities designed for this purpose.

Leveraging Built-in Configuration Logic

The Pay-i SDK is designed to automatically handle configuration precedence for API keys and base URLs. Both the client constructors (Payi, AsyncPayi) and the URL helper functions (payi_openai_url(), payi_anthropic_url(), etc.) follow this logic:

1. Explicit Parameter: If an api_key or base_url (or payi_base_url for helpers) is provided directly, that value is used.
2. Environment Variable: If no parameter is provided, the SDK checks for the corresponding environment variable (PAYI_API_KEY or PAYI_BASE_URL).
3. Default/Requirement: If neither a parameter nor an environment variable is found, the SDK will raise an error for the missing PAYI_API_KEY (as it's required), while PAYI_BASE_URL will default to "https://api.pay-i.com".

Important Note: When using payi_instrument() without passing a Payi or AsyncPayi client instance, the PAYI_API_KEY environment variable must be defined. This is because payi_instrument() creates internal client instances for telemetry that require API key authentication.

You should rely on this built-in behavior for managing configuration securely and flexibly across different environments, rather than implementing manual checks using os.getenv.

Related Resources

• Pay-i API Keys - Information on managing your Pay-i API keys
• Authentication - General authentication documentation
• Operational Approaches - Understanding direct instrumentation and proxy routing approaches
• Custom Instrumentation - Implementing tracking in your applications