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:

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 local development, you can set environment variables 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

Using .env Files (Development)

For development, you can use .env files with the python-dotenv package:

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.

Production Deployment

In production environments, set environment variables using your deployment platform's configuration:

• Kubernetes: Use Secrets and ConfigMaps
• AWS: Use Parameter Store, Secrets Manager, or environment variables in Lambda/ECS
• Azure: Use App Configuration or Key Vault
• Heroku: Use Config Vars
• Docker: Use environment variables in your Docker Compose or Dockerfile

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".

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