Authentication

Configure Komga authentication for the SDK client

Komga SDK supports multiple authentication methods. Choose the one that fits your use case.

Authentication methods

Basic Auth

Username and password authentication. Good for development and simple integrations.

API Key

Long-lived tokens for server-to-server communication. Recommended for production.

Basic Auth

The simplest authentication method using username and password.

import { createKomgaClient } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: 'http://localhost:25600',
  auth: {
    type: 'basic',
    username: '[e-mail]',
    password: 'your-password',
  },
});

Basic Auth credentials are sent with every request. The SDK handles Base64 encoding automatically.

When to use

• Local development
• Simple scripts and automation
• Testing environments

Limitations

• Credentials sent with every request
• Password rotation requires code changes
• Not ideal for distributed systems

API Key Auth

API keys are long-lived tokens generated in the Komga UI. They’re the recommended authentication method for production applications.

import { createKomgaClient } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: 'http://localhost:25600',
  auth: {
    type: 'apiKey',
    key: 'your-api-key',
  },
});

Generate an API key

1. Open Komga settings

   Navigate to your Komga server and open the user settings page.

2. Create API key

   Click “Create API Key” and provide a descriptive name (e.g., “SDK Integration”).

3. Copy the key

   Copy the generated key immediately - it won’t be shown again.

4. Store securely

   Store the key in environment variables or a secrets manager.

When to use

• Production applications
• CI/CD pipelines
• Server-to-server integrations
• Long-running services

Benefits

• Revocable without password changes
• Scoped permissions possible
• Audit trail in Komga
• No password exposure

OAuth providers

Discover configured OAuth/OpenID Connect providers:

import { getOAuth2Providers } from 'komga-sdk';

const result = await getOAuth2Providers({ client });

if (result.data) {
  result.data.forEach(provider => {
    console.log(`${provider.id}: ${provider.displayName}`);
  });
}

Session cookie conversion

If you authenticate with a session header and need a cookie for browser-based clients:

import { convertHeaderSessionToCookie } from 'komga-sdk';

const result = await convertHeaderSessionToCookie({ client });

if (result.response) {
  const setCookie = result.response.headers.get('set-cookie');
  console.log(`Cookie: ${setCookie}`);
}

Logout

Komga supports logout via both GET and POST. Use POST when possible.

import { postLogout1 } from 'komga-sdk';

await postLogout1({ client });

import { postLogout } from 'komga-sdk';

await postLogout({ client });

Security best practices

Never hardcode credentials in source code. Use environment variables or a secrets manager.

Use environment variables

.env

KOMGA_URL=http://localhost:25600
KOMGA_API_KEY=your-api-key-here

lib/komga.ts

import { createKomgaClient } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: process.env.KOMGA_URL!,
  auth: {
    type: 'apiKey',
    key: process.env.KOMGA_API_KEY!,
  },
});

Rotate credentials regularly

API key rotation strategy

1. Generate a new API key in Komga
2. Update your application with the new key
3. Verify the application works with the new key
4. Delete the old API key in Komga

Consider using a secrets manager that supports automatic rotation.

Handling expired API keys

If your API key is revoked or expired, generate a new one in the Komga UI and update your application:

// Store API key in environment variables for easy rotation
const client = createKomgaClient({
  baseUrl: process.env.KOMGA_URL!,
  auth: { type: 'apiKey', key: process.env.KOMGA_API_KEY! },
});

Disable debug in production

const client = createKomgaClient({
  baseUrl: process.env.KOMGA_URL!,
  auth: { type: 'apiKey', key: process.env.KOMGA_API_KEY! },
  debug: process.env.NODE_ENV !== 'production', // Only in dev
});

Use HTTPS in production

Production

const client = createKomgaClient({
  baseUrl: 'https://komga.example.com', // HTTPS
  auth: { type: 'apiKey', key: process.env.KOMGA_API_KEY! },
});

Development

const client = createKomgaClient({
  baseUrl: 'http://localhost:25600', // HTTP OK for local
  auth: { type: 'basic', username: 'admin', password: 'password' },
});

Comparison table

Method	Security	Ease of Use	Best For
Basic Auth	Medium	Easy	Development, scripts
API Key	High	Medium	Production, automation

Troubleshooting

401 Unauthorized

Causes:

• Incorrect username/password
• Invalid or expired API key

Solutions:

• Verify credentials are correct
• Check API key hasn’t been revoked
• Ensure user has required permissions

403 Forbidden

Causes:

• User lacks permission for the requested resource
• API key has insufficient scope

Solutions:

• Check user permissions in Komga
• Verify the user can access the library/book
• Use an admin account for full access

Connection refused

Causes:

• Komga server not running
• Wrong baseUrl
• Firewall blocking connection

Solutions:

• Verify Komga is running
• Check baseUrl includes correct port
• Test with curl or browser

Next steps

Configuration

Configure timeouts, retries, and other client options.

Best Practices

Learn security best practices for production.