Skip to content

api-configuration.md

Latest commit

 

History

History
386 lines (267 loc) · 11 KB

api-configuration.md

File metadata and controls

386 lines (267 loc) · 11 KB

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

Configuration Behavior
Encryption key set Keys encrypted with your key
No encryption key set Storing credentials is disabled

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

Provider Required Fields Optional Fields
OpenAI API Key —
Anthropic API Key —
Google Gemini API Key —
Groq API Key —
Mistral API Key —
DeepSeek API Key —
xAI API Key —
OpenRouter API Key —
Voyage AI API Key —
ElevenLabs API Key —

Local/Self-Hosted

Provider Required Fields Notes
Ollama Base URL Typically http://localhost:11434 or http://ollama:11434

Enterprise

Provider Required Fields Optional Fields
Azure OpenAI API Key, URL Base (Azure endpoint) Service-specific endpoints (LLM, Embedding, STT, TTS)
OpenAI-Compatible Base URL API Key, Service-specific configs
Vertex AI Project ID, Location, Credentials Path —

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:
Result Meaning
Success Key is valid, provider accessible
Invalid API key Check key format and value
Connection failed Check URL, network, firewall

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:

Result Meaning
Success Key is valid, provider accessible
Invalid API key Check key format and value
Connection failed Check URL, network, firewall
Model not available Key valid but model access restricted

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:

Field Example
Project ID my-gcp-project
Location us-central1
Credentials Path /path/to/service-account.json

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

Scenario Action
Key in env only Migrated to database
Key in database only No change
Key in both Database version kept (skipped)

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

Configuration Behavior
Encryption key set Keys encrypted with your key
No encryption key set Storing API keys in database is disabled

Default Credentials

Setting Default Value Production Recommendation
Password open-notebook-change-me Set OPEN_NOTEBOOK_PASSWORD
Encryption Key None (must be set) Set OPEN_NOTEBOOK_ENCRYPTION_KEY to any secret string

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

Symptom Cause Solution
Save button disabled Empty or invalid input Enter a valid key
Error on save Encryption key not set Set OPEN_NOTEBOOK_ENCRYPTION_KEY in docker-compose.yml
Error on save Database connection issue Check database status

Test Connection Fails

Error Cause Solution
Invalid API key Wrong key or format Verify key from provider dashboard
Connection refused Wrong URL Check base URL format
Timeout Network issue Check firewall, proxy settings
403 Forbidden IP restriction Whitelist your server IP

Migration Issues

Problem Solution
No migration banner No env vars detected, or already migrated
Partial migration Check error list, fix and retry
Keys not working after migration Clear browser cache, restart services

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