Skip to main content

Setting up OpenAI API Key

This guide shows you in detail how to create, manage, and configure an OpenAI API key in Shopware.

What is an API Key?​

An API key is like a password that allows your Shopware system to access your OpenAI account. It enables:

  • 🔑 Secure authentication with OpenAI
  • 💳 Attribution of usage to your account
  • 📊 Tracking of API calls and costs
  • 🔒 Control over permissions
Security Note

Treat your API key like a password! Never share it publicly and store it securely. Anyone with access to the key can make API requests at your expense.

Create OpenAI Account​

Step 1: Registration​

  1. Visit platform.openai.com
  2. Click Sign Up
  3. Choose a registration method:
    • Email address + password
    • Google account
    • Microsoft account
    • Apple account

Step 2: Verify Email​

  1. Check your email inbox
  2. Click the confirmation link in the email from OpenAI
  3. Your email address is now verified

Step 3: Create Organization (Optional)​

If using OpenAI for business:

  1. Go to Settings → Organization
  2. Enter your company name
  3. Save changes

Add Payment Method​

OpenAI works on a pay-as-you-go basis: You only pay for what you actually use.

Step 1: Open Billing Area​

  1. Log in to platform.openai.com
  2. Click your profile in the top right
  3. Select Settings → Billing
  4. Or directly: platform.openai.com/settings/organization/billing

Step 2: Add Payment Method​

  1. Click Add payment method
  2. Choose a payment method:
    • Credit card (Visa, Mastercard, American Express)
    • Or alternative methods (depending on region)
  3. Enter your payment details
  4. Click Save payment method

Step 3: Load Initial Credit​

  1. OpenAI requires a minimum credit (usually $5-10)
  2. Choose an amount (e.g., $20)
  3. Click Continue
  4. Confirm payment
Budget Recommendation

For a small to medium online shop, $10-20 per month is completely sufficient. With token caching (50-90% savings), actual costs are often even lower!

Step 4: Set up Auto Recharge (Optional)​

  1. Go to Billing → Auto recharge
  2. Enable automatic recharge
  3. Set:
    • Threshold: At what balance to recharge? (e.g., $5)
    • Recharge amount: How much to recharge? (e.g., $20)
  4. Save settings

This prevents your agent from suddenly stopping when balance runs out.

Protect yourself from unexpected costs:

  1. Go to Billing → Limits
  2. Set a monthly budget limit (e.g., $50)
  3. Enable email notifications at 80% and 100%
  4. Save
Budget Protected

When your limit is reached, OpenAI automatically stops all requests – so no surprising costs can occur!

Create API Key​

Step 1: Open API Keys Area​

  1. Go to Settings → API keys
  2. Or directly: platform.openai.com/api-keys

Step 2: Create New Key​

  1. Click + Create new secret key
  2. A dialog opens

Step 3: Configure Key​

Name (required):

Shopware Production

Choose a meaningful name so you know later what this key is used for

Permissions:

  • Choose All (all permissions)
  • Or for more security: Only Model capabilities

Project (Optional):

  • If you use projects, select the appropriate one
  • Otherwise: Default project

Step 4: Create and Copy Key​

  1. Click Create secret key
  2. The key is only displayed once!
  3. Click Copy
  4. Save the key in a secure location (e.g., password manager)

The key looks like this:

sk-proj-aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abcdefghijklmnopqrstuvwxyz...
Only visible once!

OpenAI displays the key only once. If you didn't copy it or lose it, you must create a new key. The old one cannot be recovered!

Step 5: Confirm Key​

  1. Check the box for "I have saved my key"
  2. Click Done

Enter API Key in Shopware​

  1. Log in to Shopware backend
  2. Go to Settings → System → Plugins
  3. Search for OpenAI Agents Manager (FelOAIAssistantsManager)
  4. Click the three dots (⋮) → Configure
  1. Find the field "API Key for the Agent Manager"
  2. Paste your copied OpenAI API key
  3. Click Test API Key (button appears after entry)
  4. On successful test, a green success message appears
  5. Click Save
Connection Established

If the test was successful, your Shopware system is now connected to OpenAI!

Method 2: Via Environment Variables (Advanced)​

For more security, you can also store the API key as an environment variable:

  1. Open your .env file in the Shopware root
  2. Add:
OPENAI_API_KEY=sk-proj-YourKeyHere...
  1. Save the file
  2. Clear cache:
bin/console cache:clear

The plugin will then automatically read the key from the environment variable.

Test API Key​

Test in Plugin​

The plugin offers an integrated test:

  1. Go to plugin configuration
  2. Enter the API key
  3. Click "Test API Key"

The system checks:

  • ✅ Is the key valid?
  • ✅ Does the OpenAI account have credit?
  • ✅ Are permissions correct?

Test via Backend Chat​

Alternatively, you can perform a live test:

  1. Open 5E OAI Agent Manager → Chat
  2. If you've already created an agent, send a test message
  3. If a response comes, everything works! ✅

Manage API Keys​

Use Multiple Keys​

You can create multiple API keys:

  • Production key: For live shop
  • Test key: For development/staging
  • Backup key: In case main key is compromised

Change Key Permissions​

  1. Go to platform.openai.com/api-keys
  2. Click on the key
  3. Change permissions
  4. Save

Deactivate/Delete Key​

If a key has been compromised:

  1. Go to platform.openai.com/api-keys
  2. Find the affected key
  3. Click Revoke
  4. Confirm
Deactivate Immediately!

If you suspect your API key has been made public (e.g., accidentally uploaded to GitHub), deactivate it immediately!

Create New Key (if old one lost)​

  1. Create a new key (see above)
  2. Enter it in Shopware
  3. (Optional) Delete the old key in OpenAI

Monitor Usage & Costs​

OpenAI Dashboard​

Keep track of your costs:

  1. Go to platform.openai.com/usage
  2. Here you'll see:
    • Daily API calls
    • Cost per day/month
    • Used model mix
    • Token consumption

Understanding Important Metrics​

MetricMeaning
RequestsNumber of API requests
TokensProcessed text units
CostCost in USD
Cached TokensTokens saved through caching

Email Notifications​

Enable notifications:

  1. Go to Settings → Billing → Notifications
  2. Enable:
    • ✅ Daily usage summary
    • ✅ Budget warnings (at 80%, 90%, 100%)
    • ✅ Low balance

Cost Optimization​

Use Token Caching​

The plugin automatically uses OpenAI's prompt caching:

  • 🎯 50-90% cost savings on repeated requests
  • 📊 Cached tokens cost only a fraction (e.g., $0.08 instead of $0.15 per 1M tokens)

No configuration needed – works automatically!

Choose Cheaper Model​

ModelCost (Input)SpeedRecommendation
gpt-4o-mini$0.15 / 1M tokens⚡⚡⚡ Very fast✅ Start here
gpt-4o$2.50 / 1M tokens⚡⚡ FastFor complex tasks
gpt-5~$5.00 / 1M tokens⚡ SlowOnly if necessary

Reduce Tools​

The fewer tools activated, the:

  • ⬇️ Fewer tokens in instructions
  • ⬇️ Fewer function calls
  • ⬇️ Lower costs

Only activate tools you really need!

Troubleshooting​

Problem: "Invalid API Key"​

Causes:

  • Key copied incorrectly (spaces at beginning/end?)
  • Key was revoked
  • Key belongs to different organization

Solution:

  1. Copy the key again
  2. Check for spaces
  3. Create new key if necessary

Problem: "Insufficient quota"​

Meaning: Your OpenAI credit is used up.

Solution:

  1. Go to platform.openai.com/settings/organization/billing
  2. Add credit
  3. Or enable automatic recharge

Problem: "Rate limit exceeded"​

Meaning: Too many requests in a short time.

Solution:

  • Wait 1-2 minutes
  • Increase rate limit in OpenAI (for paying customers)

Problem: API Key doesn't work in Shopware​

Checklist:

  1. ✅ Is the plugin activated?
  2. ✅ Is the key copied completely?
  3. ✅ Does the OpenAI account have credit?
  4. ✅ Was the cache cleared? (bin/console cache:clear)

Next Steps​

You have now:

  • ✅ Created an OpenAI account
  • ✅ Added a payment method
  • ✅ Generated an API key
  • ✅ Entered the key in Shopware

Continue with:

➡️ Creating Your First Agent - Step-by-step guide

➡️ Agent Configuration - All settings explained

➡️ Cost Management - Optimize and monitor costs