Skip to main content

​
API Key Authentication

All requests to the OpenAI API require authentication using an API key. The Ruby SDK handles this automatically through the client configuration.

​
Setting Your API Key

1

Get your API key

Obtain your API key from the OpenAI Platform.
2

Configure the client

Pass your API key when creating the client:
client = OpenAI::Client.new(api_key: 'sk-...')
Or set it as an environment variable:
export OPENAI_API_KEY="sk-..."

client = OpenAI::Client.new  # Uses ENV["OPENAI_API_KEY"]

​
How Authentication Works

The SDK automatically includes your API key in the Authorization header of every request: 
# lib/openai/client.rb:99-103
private def auth_headers
  return {} if @api_key.nil?

  {"authorization" => "Bearer #{@api_key}"}
end
Never hardcode API keys in your source code. Use environment variables or a secure configuration management system.

​
Organization Header

For users with multiple organizations, you can specify which organization to use for API requests.

​
Configuring Organization ID

client = OpenAI::Client.new(
  api_key: 'your-api-key',
  organization: 'org-abc123'
)
Or via environment variable: 
export OPENAI_ORG_ID="org-abc123"

​
How It Works

The organization ID is sent in the openai-organization header: 
# lib/openai/client.rb:142-145
headers = {
  "openai-organization" => (@organization = organization&.to_s),
  "openai-project" => (@project = project&.to_s)
}

​
Project Header

Projects allow you to organize your API usage and manage resources within an organization.

​
Configuring Project ID

client = OpenAI::Client.new(
  api_key: 'your-api-key',
  project: 'proj_abc123'
)
Or via environment variable: 
export OPENAI_PROJECT_ID="proj_abc123"

​
How It Works

The project ID is sent in the openai-project header on all requests, scoping your API calls to the specified project.

​
Complete Configuration Example

# Set in your shell or .env file
export OPENAI_API_KEY="sk-..."
export OPENAI_ORG_ID="org-abc123"
export OPENAI_PROJECT_ID="proj_xyz789"

# In your application
require 'openai'

client = OpenAI::Client.new

​
Security Best Practices

Follow these guidelines to keep your API keys secure:
  • Never commit API keys to version control - Use .gitignore to exclude configuration files
  • Use environment variables - Store sensitive credentials outside your codebase
  • Rotate keys regularly - Generate new API keys periodically
  • Use project-scoped keys - Limit key permissions to specific projects when possible
  • Monitor usage - Track API usage in the OpenAI dashboard to detect unauthorized access

​
Missing API Key Error

If no API key is provided, the client will raise an error: 
# lib/openai/client.rb:138-140
if api_key.nil?
  raise ArgumentError.new("api_key is required, and can be set via environ: \"OPENAI_API_KEY\"")
end
Error message: 
ArgumentError: api_key is required, and can be set via environ: "OPENAI_API_KEY"
Ensure your API key is set before attempting to make API requests.

Build docs developers (and LLMs) love

Get started for freeTalk to us