API Configuration

Configure AI provider credentials through the Settings UI. No file editing required.

Credential System: Open Notebook uses encrypted credentials stored in the database. Each credential connects to a provider and allows you to discover, register, and test models.

Overview

Open Notebook manages AI provider access through a credential-based system:

1. You create a credential for each provider (API key + settings)
2. Credentials are encrypted and stored in the database
3. You test connections to verify credentials work
4. You discover and register models from each credential
5. Models are linked to credentials for direct configuration

Encryption Setup

Before storing credentials, you must configure an encryption key.

Setting the Encryption Key

Add OPEN_NOTEBOOK_ENCRYPTION_KEY to your docker-compose.yml:

environment:
  - OPEN_NOTEBOOK_ENCRYPTION_KEY=my-secret-passphrase

Any string works as a key — it will be securely derived via SHA-256 internally.

Warning: If you change or lose the encryption key, all stored credentials become unreadable. Back up your encryption key securely and separately from your database backups.

Docker Secrets Support

Both password and encryption key support Docker secrets:

# docker-compose.yml
services:
  open_notebook:
    environment:
      - OPEN_NOTEBOOK_PASSWORD_FILE=/run/secrets/app_password
      - OPEN_NOTEBOOK_ENCRYPTION_KEY_FILE=/run/secrets/encryption_key
    secrets:
      - app_password
      - encryption_key

secrets:
  app_password:
    file: ./secrets/password.txt
  encryption_key:
    file: ./secrets/encryption_key.txt

Encryption Details

API keys stored in the database are encrypted using Fernet (AES-128-CBC + HMAC-SHA256).

Accessing Credential Configuration

1. Click Settings in the navigation bar
2. Select API Keys tab
3. You'll see existing credentials and an Add Credential button

Navigation: Settings → API Keys

Supported Providers

Cloud Providers

Local/Self-Hosted

Enterprise

Creating a Credential

Step 1: Add Credential

1. Go to Settings → API Keys
2. Click Add Credential
3. Select your provider
4. Give it a descriptive name (e.g., "My OpenAI Key", "Work Anthropic")
5. Fill in the required fields (API key, base URL, etc.)
6. Click Save

Step 2: Test Connection

1. On your new credential card, click Test Connection
2. Wait for the result:

Step 3: Discover Models

1. Click Discover Models on the credential card
2. The system queries the provider for available models
3. Review the discovered models

Step 4: Register Models

1. Select the models you want to use
2. Click Register Models
3. The models are now available throughout Open Notebook

Multi-Credential Support

Each provider can have multiple credentials. This is useful when:

• You have different API keys for different projects
• You want to test with different endpoints
• Multiple team members need separate credentials

Creating Multiple Credentials

1. Click Add Credential again
2. Select the same provider
3. Fill in different credentials
4. Each credential can discover and register its own models

How Models Link to Credentials

When you register models from a credential, those models are linked to that specific credential. This means:

• Each model knows which API key to use
• You can have models from different credentials for the same provider
• Deleting a credential removes its linked models

Testing Connections

Click Test Connection to verify your credential:

Test uses inexpensive models (e.g., gpt-3.5-turbo, claude-3-haiku) to minimize cost.

Configuring Specific Providers

Simple Providers (API Key Only)

For OpenAI, Anthropic, Google, Groq, Mistral, DeepSeek, xAI, OpenRouter:

1. Add credential with your API key
2. Test connection
3. Discover and register models

Ollama (URL-Based)

1. Add credential with provider Ollama
2. Enter the base URL (e.g., http://ollama:11434)
3. Test connection
4. Discover and register models

Ollama allows localhost and private IPs since it runs locally.

Azure OpenAI

1. Add credential with provider Azure OpenAI
2. Enter your API key
3. Enter your Azure endpoint in the URL Base field (e.g., https://myresource.openai.azure.com)
4. Test connection
5. Discover and register models

The URL Base field is automatically mapped to the Azure endpoint. The API version defaults to 2024-10-21 if not set via environment variable.

OpenAI-Compatible

For custom OpenAI-compatible servers (LM Studio, vLLM, etc.):

1. Add credential with provider OpenAI-Compatible
2. Enter the base URL
3. Enter API key (if required)
4. Optionally configure per-service URLs

Supports separate configurations for:

• LLM (language models)
• Embedding
• STT (speech-to-text)
• TTS (text-to-speech)

Vertex AI

Google Cloud's enterprise AI platform:

Migrating from Environment Variables

If you have existing API keys in environment variables (from a previous version):

1. Open Settings → API Keys
2. A banner appears: "Environment variables detected"
3. Click Migrate to Database
4. Keys are copied to the database (encrypted)
5. Original environment variables remain unchanged

Migration Behavior

After Migration

• Database credentials are used for all operations
• You can remove the API key environment variables from your docker-compose.yml
• Keep OPEN_NOTEBOOK_ENCRYPTION_KEY — it's still required

Migration Banner Visibility

The migration banner only appears when:

• You have environment variables configured
• Those providers are not already in the database
• If all env providers are already migrated, the banner won't show

Migrating from ProviderConfig (v1.1 → v1.2)

If you're upgrading from an older version that used the ProviderConfig system:

• The migration happens automatically on first startup
• Your existing configurations are converted to credentials
• Check Settings → API Keys to verify the migration succeeded
• If you see issues, check the API logs for migration messages

Key Storage Security

Encryption

API keys stored in the database are encrypted using Fernet (AES-128-CBC + HMAC-SHA256).

Default Credentials

For production deployments, always set custom credentials.

Deleting Credentials

1. Click the Delete button on the credential card
2. Confirm deletion
3. Credential and all its linked models are removed from the database

Troubleshooting

Credential Not Saving

Test Connection Fails

Migration Issues

Provider Shows "Not Configured"

1. Check if a credential exists for this provider (Settings → API Keys)
2. Test the credential connection
3. Verify key format matches provider requirements
4. Re-discover and register models if needed

Provider-Specific Notes

OpenAI

• Keys start with sk-proj- (project keys) or sk- (legacy)
• Requires billing enabled on account

Anthropic

• Keys start with sk-ant-
• Check account has API access enabled

Google Gemini

• Keys start with AIzaSy
• Free tier has rate limits

Ollama

• No API key required
• Default URL: http://localhost:11434 (local) or http://ollama:11434 (Docker)
• Ensure Ollama server is running

Azure OpenAI

• Enter your Azure endpoint in the URL Base field (format: https://{resource-name}.openai.azure.com)
• API version defaults to 2024-10-21; override via AZURE_OPENAI_API_VERSION environment variable if needed
• Deployment names configured separately when registering models via the credential's Discover Models dialog

Related

• AI Providers — Provider setup instructions and recommendations
• Security — Password and encryption configuration
• Environment Reference — All configuration options